Data Types

Bro/Zeek Types

Bro/Zeek data types.

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

Bases: zlogging.types._SimpleType

Bro/Zeek bool data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, bool]) – raw data

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.

Return type

Union[None, bool]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, bool]) – raw data

Returns

The JSON serialisable boolean data.

Return type

Union[None, bool]

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, bool]) – raw data

Returns

T if True, F if False.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek count data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, ctypes.c_ulong]) – raw data

Returns

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

Return type

Union[None, ctypes.c_ulong]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, ctypes.c_ulong]) – raw data

Returns

The JSON serialisable numeral data.

Return type

int

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, ctypes.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)

Bases: zlogging.types._SimpleType

Bro/Zeek int data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, ctypes.c_long]) – raw data

Returns

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

Return type

Union[None, ctypes.c_long]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, ctypes.c_long]) – raw data

Returns

The JSON serialisable numeral data.

Return type

int

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, ctypes.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)

Bases: zlogging.types._SimpleType

Bro/Zeek double data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, decimal.Decimal]) – raw data

Returns

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

Return type

Union[None, decimal.Decimal]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, decimal.Decimal]) – raw data

Returns

The JSON serialisable numeral data.

Return type

float

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, decimal.Decimal]) – raw data

Returns

The ASCII representation of numeral data.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek time data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, datetime.datetime]) – raw data

Returns

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

Return type

Union[None, datetime.datetime]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, datetime.datetime]) – raw data

Returns

The JSON serialisable numeral data.

Return type

int

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, datetime.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)

Bases: zlogging.types._SimpleType

Bro/Zeek interval data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, datetime.timedelta]) – raw data

Returns

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

Return type

Union[None, datetime.timedelta]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, datetime.timedelta]) – raw data

Returns

The JSON serialisable numeral data.

Return type

int

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, datetime.timedelta]) – raw data

Returns

The ASCII representation of numeral data.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek string data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, memoryview, bytearray]) – raw data

Returns

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

Return type

Union[None, ByteString]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, ByteString]) – raw data

Returns

The JSON serialisable string data encoded in ASCII.

Return type

str

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, ByteString]) – raw data

Returns

The ASCII encoded string data.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek addr data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, ipaddress.IPv4Address, ipaddress.IPv6Address]) – raw data

Returns

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

Return type

Union[None, ipaddress.IPv4Address, ipaddress.IPv6Address]

tojson(data)

Serialize data as JSON log format.

Parameters

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

Returns

The JSON serialisable IP address string.

Return type

str

toascii(data)

Serialize data as ASCII log format.

Parameters

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

Returns

The ASCII representation of the IP address.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek port data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, ctypes.c_ushort]) – raw data

Returns

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

Return type

Union[None, ctypes.c_ushort]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, ctypes.c_ushort]) – raw data

Returns

The JSON serialisable port number string.

Return type

int

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, ctypes.c_ushort]) – raw data

Returns

The ASCII representation of the port number.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek subnet data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, ipaddress.IPv4Network, ipaddress.IPv6Network]) – raw data

Returns

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

Return type

Union[None, ipaddress.IPv4Network, ipaddress.IPv6Network]

tojson(data)

Serialize data as JSON log format.

Parameters

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

Returns

The JSON serialisable IP network string.

Return type

str

toascii(data)

Serialize data as ASCII log format.

Parameters

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

Returns

The ASCII representation of the IP network.

Return type

str

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

Bases: zlogging.types._SimpleType

Bro/Zeek enum data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • namespaces (List[str], optional) – Namespaces to be loaded.

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

  • enum_hook (dict mapping of str and enum.Enum, optional) – Additional enum to be included in the namespace.

  • *args – Variable length argument list.

  • **kwargs – 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.

  • enum_namespaces (dict mapping str and enum.Enum) – Global namespace for enum data type.

property python_type

type: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, enum.Enum]) – raw data

Returns

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

Warns

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

Return type

Union[None, enum.Enum]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, enum.Enum]) – raw data

Returns

The JSON serialisable enum data.

Return type

str

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, enum.Enum]) – raw data

Returns

The ASCII representation of the enum data.

Return type

str

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

Bases: zlogging.types._GenericType, typing.Generic

Bro/Zeek set data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • element_type (BaseType instance) – Data type of container’s elements.

  • *args – Variable length argument list.

  • **kwargs – 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.

  • element_type (BaseType instance) – Data type of container’s elements.

Raises

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

type: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, Set[data]]) – raw data

Returns

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

Return type

Union[None, Set[data]]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, Set[data]]) – raw data

Returns

The JSON serialisable set data.

Return type

list

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, Set[data]]) – raw data

Returns

The ASCII representation of the set data.

Return type

str

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

Bases: zlogging.types._GenericType, typing.Generic

Bro/Zeek vector data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • element_type (BaseType instance) – Data type of container’s elements.

  • *args – Variable length argument list.

  • **kwargs – 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.

  • element_type (BaseType instance) – Data type of container’s elements.

Raises

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

type: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

parse(data)

Parse data from string.

Parameters

data (Union[AnyStr, List[data]]) – raw data

Returns

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

Return type

Union[None, List[data]]

tojson(data)

Serialize data as JSON log format.

Parameters

data (Union[None, List[data]]) – raw data

Returns

The JSON serialisable list data.

Return type

list

toascii(data)

Serialize data as ASCII log format.

Parameters

data (Union[None, List[data]]) – 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)

Bases: zlogging.types._VariadicType

Bro/Zeek record data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – element_mapping (dict mapping str and BaseType instance): Data type of container’s elements.

Variables

  • empty_field (bytes) – Placeholder for empty field.

  • unset_field (bytes) – Placeholder for unset field.

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

  • element_mapping (dict mapping str and BaseType instance) – Data type of container’s elements.

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.

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

type: Corresponding Python type annotation.

property zeek_type

str: Corresponding Zeek type name.

Abstract Base Types

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

Bases: object

Base Bro/Zeek data type.

Parameters

  • empty_field (bytes or str, optional) – Placeholder for empty field.

  • unset_field (bytes or str, optional) – Placeholder for unset field.

  • set_separator (bytes or str, optional) – Separator for set/vector fields.

  • *args – Variable length argument list.

  • **kwargs – 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.

abstract property python_type

type: Corresponding Python type annotation.

abstract property zeek_type

str: Corresponding Zeek type name.

property bro_type

str: Corresponding Bro type name.

__call__(data)

Parse data from string.

Parameters

data (Any) –

Return type

Any

abstract parse(data)

Parse data from string.

Parameters

data (Any) –

Return type

Any

abstract tojson(data)

Serialize data as JSON log format.

Parameters

data (Any) –

Return type

Any

abstract toascii(data)

Serialize data as ASCII log format.

Parameters

data (Any) –

Return type

str

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

Bases: zlogging.types.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 (Optional[AnyStr]) –

  • unset_field (Optional[AnyStr]) –

  • set_separator (Optional[AnyStr]) –

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

Bases: zlogging.types.BaseType

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 (Optional[AnyStr]) –

  • unset_field (Optional[AnyStr]) –

  • set_separator (Optional[AnyStr]) –

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

Bases: zlogging.types.BaseType

Variadic data type.

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

Parameters

  • empty_field (Optional[AnyStr]) –

  • unset_field (Optional[AnyStr]) –

  • set_separator (Optional[AnyStr]) –

parse(data)

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)

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)

Not supported for a variadic data type.

Parameters

data (Any) – data to process

Raises

ZeekNotImplemented – If try to call such method.

Return type

NoReturn

Internal Data

zlogging.types._data = ~data

A typing variable representing all valid data types for Bro/Zeek log framework.

Type

type