Data Types

Bro/Zeek Types

Boolean

class zlogging.types.BoolType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek bool data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[bool]

Corresponding Python type annotation.

property zeek_type: Literal['bool']

Corresponding Zeek type name.

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, bool]) – raw data

Return type:

Optional[bool]

Returns:

The parsed boolean data. If data is unset, None will be returned.

Raises:

ZeekValueError – If data is NOT unset and NOT T (True) nor F (False) in Bro/Zeek script language.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[bool]) – raw data

Return type:

Optional[bool]

Returns:

The JSON serialisable boolean data.

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[bool]) – raw data

Returns:

T if True, F if False.

Return type:

str

Numeric Types

class zlogging.types.CountType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek count data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[c_ulong]

Corresponding Python type annotation.

property zeek_type: Literal['count']

Corresponding Zeek type name.

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, int, c_ulong]) – raw data

Return type:

Optional[c_ulong]

Returns:

The parsed numeral data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[c_ulong]) – raw data

Returns:

The JSON serialisable numeral data.

Return type:

int

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[c_ulong]) – raw data

Returns:

The ASCII representation of numeral data.

Return type:

str

class zlogging.types.IntType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek int data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[c_long]

Corresponding Python type annotation.

property zeek_type: Literal['int']

Corresponding Zeek type name.

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, int, c_long]) – raw data

Return type:

Optional[c_long]

Returns:

The parsed numeral data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[c_long]) – raw data

Returns:

The JSON serialisable numeral data.

Return type:

int

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[c_long]) – raw data

Returns:

The ASCII representation of numeral data.

Return type:

str

class zlogging.types.DoubleType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek double data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[Decimal]

Corresponding Python type annotation.

property zeek_type: Literal['double']

Corresponding Zeek type name.

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, int, float, Decimal]) – raw data

Return type:

Optional[Decimal]

Returns:

The parsed numeral data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[Decimal]) – raw data

Returns:

The JSON serialisable numeral data.

Return type:

float

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[Decimal]) – raw data

Returns:

The ASCII representation of numeral data.

Return type:

str

Time Types

class zlogging.types.TimeType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek time data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[datetime]

Corresponding Python type annotation.

Type:

Any

property zeek_type: Literal['time']

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, float, datetime]) – raw data

Return type:

Optional[datetime]

Returns:

The parsed numeral data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[datetime]) – raw data

Returns:

The JSON serialisable numeral data.

Return type:

float

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[datetime]) – raw data

Returns:

The ASCII representation of numeral data.

Return type:

str

class zlogging.types.IntervalType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek interval data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Variables:

  • empty_field (bytes) – Placeholder for empty field.

  • unset_field (bytes) – Placeholder for unset field.

  • set_separator (bytes) – Separator for set/vector fields.

property python_type: Type[timedelta]

Corresponding Python type annotation.

Type:

Any

property zeek_type: Literal['interval']

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, float, timedelta]) – raw data

Return type:

Optional[timedelta]

Returns:

The parsed numeral data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[timedelta]) – raw data

Returns:

The JSON serialisable numeral data.

Return type:

int

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[timedelta]) – raw data

Returns:

The ASCII representation of numeral data.

Return type:

str

String

class zlogging.types.StringType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek string data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: Literal['string']

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, bytearray, memoryview]) – raw data

Return type:

Optional[bytes]

Returns:

The parsed string data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Union[bytes, bytearray, memoryview, None]) – raw data

Returns:

The JSON serialisable string data encoded in ASCII.

Return type:

str

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Union[bytes, bytearray, memoryview, None]) – raw data

Returns:

The ASCII encoded string data.

Return type:

str

Network Types

class zlogging.types.PortType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek port data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Type[c_ushort]

Corresponding Python type annotation.

Type:

Any

property zeek_type: Literal['port']

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, int, c_ushort]) – raw data

Return type:

Optional[c_ushort]

Returns:

The parsed port number. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[c_ushort]) – raw data

Returns:

The JSON serialisable port number string.

Return type:

int

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[c_ushort]) – raw data

Returns:

The ASCII representation of the port number.

Return type:

str

class zlogging.types.AddrType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek addr data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: str

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, IPv4Address, IPv6Address]) – raw data

Return type:

Union[IPv4Address, IPv6Address, None]

Returns:

The parsed IP address. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Union[IPv4Address, IPv6Address, None]) – raw data

Returns:

The JSON serialisable IP address string.

Return type:

str

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Union[IPv4Address, IPv6Address, None]) – raw data

Returns:

The ASCII representation of the IP address.

Return type:

str

class zlogging.types.SubnetType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek subnet data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: Literal['subnet']

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, IPv4Network, IPv6Network]) – raw data

Return type:

Union[IPv4Network, IPv6Network, None]

Returns:

The parsed IP network. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Union[IPv4Network, IPv6Network, None]) – raw data

Returns:

The JSON serialisable IP network string.

Return type:

str

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Union[IPv4Network, IPv6Network, None]) – raw data

Returns:

The ASCII representation of the IP network.

Return type:

str

Enumeration

class zlogging.types.EnumType(empty_field=None, unset_field=None, set_separator=None, namespaces=None, bare=False, enum_hook=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek enum data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • namespaces (Optional[list[str]]) – Namespaces to be loaded.

  • bare (bool) – If True, do not load zeek namespace by default.

  • enum_hook (Optional[dict[str, Enum]]) – Additional enum to be included in the namespace.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: str

Corresponding Zeek type name.

Type:

str

enum_namespaces: dict[str, Enum]

Namespaces to be loaded.

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, Enum]) – raw data

Return type:

Optional[Enum]

Returns:

The parsed enum data. If data is unset, None will be returned.

Warns:

ZeekValueWarning – If date is not defined in the enum namespace.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[Enum]) – raw data

Returns:

The JSON serialisable enum data.

Return type:

str

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[Enum]) – raw data

Returns:

The ASCII representation of the enum data.

Return type:

str

Container Types

class zlogging.types.SetType(empty_field=None, unset_field=None, set_separator=None, element_type=None, *args, **kwargs)[source]

Bases: _GenericType, Generic[_S]

Bro/Zeek set data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • element_type (Union[TypeVar(_S, bound= _SimpleType), Type[TypeVar(_S, bound= _SimpleType)], None]) – Data type of container’s elements.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Raises:

  • ZeekTypeError – If element_type is not supplied.

  • ZeekValueError – If element_type is not a valid Bro/Zeek data type.

Example

As a generic data type, the class supports the typing proxy as introduced PEP 484:

>>> SetType[StringType]

which is the same at runtime as following:

>>> SetType(element_type=StringType())

Note

A valid element_type should be a simple data type, i.e. a subclass of _SimpleType.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: str

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, set[TypeVar(_S, bound= _SimpleType)]]) – raw data

Return type:

Optional[set[TypeVar(_S, bound= _SimpleType)]]

Returns:

The parsed set data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[set[TypeVar(_S, bound= _SimpleType)]]) – raw data

Return type:

Optional[list[Optional[TypeVar(_T)]]]

Returns:

The JSON serialisable set data.

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[set[TypeVar(_S, bound= _SimpleType)]]) – raw data

Return type:

str

Returns:

The ASCII representation of the set data.

class zlogging.types.VectorType(empty_field=None, unset_field=None, set_separator=None, element_type=None, *args, **kwargs)[source]

Bases: _GenericType, Generic[_S]

Bro/Zeek vector data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • element_type (Union[TypeVar(_S, bound= _SimpleType), Type[TypeVar(_S, bound= _SimpleType)], None]) – Data type of container’s elements.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Raises:

  • ZeekTypeError – If element_type is not supplied.

  • ZeekValueError – If element_type is not a valid Bro/Zeek data type.

Example

As a generic data type, the class supports the typing proxy as introduced PEP 484:

>>> VectorType[StringType]

which is the same at runtime as following:

>>> VectorType(element_type=StringType())

Note

A valid element_type should be a simple data type, i.e. a subclass of _SimpleType.

property python_type: Any

Corresponding Python type annotation.

Type:

Any

property zeek_type: str

Corresponding Zeek type name.

Type:

str

parse(data)[source]

Parse data from string.

Parameters:

data (Union[str, bytes, list[TypeVar(_S, bound= _SimpleType)]]) – raw data

Return type:

Optional[list[TypeVar(_S, bound= _SimpleType)]]

Returns:

The parsed list data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Optional[list[TypeVar(_S, bound= _SimpleType)]]) – raw data

Returns:

The JSON serialisable list data.

Return type:

list

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Optional[list[TypeVar(_S, bound= _SimpleType)]]) – raw data

Returns:

The ASCII representation of the list data.

Return type:

str

class zlogging.types.RecordType(empty_field=None, unset_field=None, set_separator=None, *args, **element_mapping)[source]

Bases: _VariadicType

Bro/Zeek record data type.

Parameters:
Raises:

  • ZeekTypeError – If element_mapping is not supplied.

  • ZeekValueError – If element_mapping is not a valid Bro/Zeek data type; or in case of inconsistency from empty_field, unset_field and set_separator of each field.

Return type:

RecordType

Note

A valid element_mapping should be a simple or generic data type, i.e. a subclass of _SimpleType or _GenericType.

See also

See _aux_expand_typing() for more information about processing the fields.

property python_type: Any

Corresponding Python type annotation.

property zeek_type: Literal['record']

Corresponding Zeek type name.

Any type

class zlogging.types.AnyType(empty_field=None, unset_field=None, set_separator=None, json_encoder=None, *args, **kwargs)[source]

Bases: _SimpleType

Bro/Zeek any data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • json_encoder (Optional[Type[JSONEncoder]]) – JSON encoder class for tojson() method calls.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Note

The AnyType is only used for arbitrary typing as required in JSONParser. It is NOT a valid type of Bro/Zeek logging framework.

property python_type: Any

Corresponding Python type annotation.

property zeek_type: Literal['any']

Corresponding Zeek type name.

json_encoder: Type[JSONEncoder]

JSON encoder class for tojson() method calls.

parse(data)[source]

Parse data from string.

Parameters:

data (TypeVar(_T)) – raw data

Return type:

Optional[TypeVar(_T)]

Returns:

The parsed data. If data is unset, None will be returned.

tojson(data)[source]

Serialize data as JSON log format.

Parameters:

data (Any) – raw data

Return type:

Any

Returns:

The JSON representation of data.

Notes

If the data is not JSON serialisable, i.e. json.dumps() raises TypeError, the method will return a dict object with data representing str sanitised raw data and error representing the error message.

toascii(data)[source]

Serialize data as ASCII log format.

Parameters:

data (Any) – raw data

Return type:

str

Returns:

The ASCII representation of data.

Abstract Base Types

class zlogging.types.BaseType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: object

Base Bro/Zeek data type.

Parameters:

  • empty_field (Union[str, bytes, None]) – Placeholder for empty field.

  • unset_field (Union[str, bytes, None]) – Placeholder for unset field.

  • set_separator (Union[str, bytes, None]) – Separator for set/vector fields.

  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

abstract property python_type: Any

Corresponding Python type annotation.

abstract property zeek_type: str

Corresponding Zeek type name.

property bro_type: str

Corresponding Bro type name.

empty_field: bytes

Placeholder for empty field.

str_empty_field: str
unset_field: bytes

Placeholder for unset field.

str_unset_field: str
set_separator: bytes

Separator for set/vector fields.

str_set_separator: str
__call__(data)[source]

Parse data from string.

This is a proxy method which calls to parse() of the type implementation.

Return type:

Any

Parameters:

data (Any)

__str__()[source]

Returns the corresponding Zeek type name.

Return type:

str

abstract parse(data)[source]

Parse data from string.

Return type:

Any

Parameters:

data (Any)

abstract tojson(data)[source]

Serialize data as JSON log format.

Return type:

Any

Parameters:

data (Any)

abstract toascii(data)[source]

Serialize data as ASCII log format.

Return type:

str

Parameters:

data (Any)

class zlogging.types._SimpleType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: BaseType

Simple data type.

In Bro/Zeek script language, such simple type includes bool, count, int, double, time, interval, string, addr, port, subnet and enum.

To support arbitrary typing as required in JSONParser, any, the arbitrary date type is also included.

Parameters:

  • empty_field (bytes)

  • unset_field (bytes)

  • set_separator (bytes)

  • args (Any)

  • kwargs (Any)

class zlogging.types._GenericType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: BaseType, Generic[_S]

Generic data type.

In Bro/Zeek script language, such generic type includes set and vector, which are also known as container types.

Parameters:

  • empty_field (bytes)

  • unset_field (bytes)

  • set_separator (bytes)

  • args (Any)

  • kwargs (Any)

element_type: TypeVar(_S, bound= _SimpleType)

Data type of container’s elements.

class zlogging.types._VariadicType(empty_field=None, unset_field=None, set_separator=None, *args, **kwargs)[source]

Bases: BaseType

Variadic data type.

In Bro/Zeek script language, such variadic type refers to record, which is also a container type.

Parameters:

  • empty_field (bytes)

  • unset_field (bytes)

  • set_separator (bytes)

  • args (Any)

  • kwargs (Any)

element_mapping: OrderedDict[str, Union[_SimpleType, _GenericType]]

Data type of container’s elements.

parse(data)[source]

Not supported for a variadic data type.

Parameters:

data (Any) – data to process

Raises:

ZeekNotImplemented – If try to call such method.

Return type:

NoReturn

tojson(data)[source]

Not supported for a variadic data type.

Parameters:

data (Any) – data to process

Raises:

ZeekNotImplemented – If try to call such method.

Return type:

NoReturn

toascii(data)[source]

Not supported for a variadic data type.

Parameters:

data (Any) – data to process

Raises:

ZeekNotImplemented – If try to call such method.

Return type:

NoReturn