Loaders

Predefined Loaders

Bro/Zeek log loader.

class zlogging.loader.JSONParser(model=None)

Bases: zlogging.loader.BaseParser

JSON log parser.

Parameters

model (Model class, optional) – Field declrations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

Variables

model (Model class, optional) – Field declrations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

Warns

JSONParserWarning – If model is not specified.

property format

str: Log file format.

parse_file(file)

Parse log file.

Parameters

file (_io.BufferedReader) – Log file object opened in binary mode.

Returns

The parsed log as a

Model per line.

Return type

JSONInfo

parse_line(line, lineno=0)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

Returns

The parsed log as a plain dict.

Raises

JSONParserError – If failed to serialise the line from JSON.

Return type

Dict[str, Any]

class zlogging.loader.ASCIIParser(type_hook=None, enum_namespaces=None, bare=False)

Bases: zlogging.loader.BaseParser

ASCII log parser.

Parameters

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

Variables

• __type__ (dict mapping str and BaseType class) – Bro/Zeek type parser hooks.

• enum_namespaces (List[str]) – Namespaces to be loaded.

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

property format

str: Log file format.

parse_file(file)

Parse log file.

Parameters

file (_io.BufferedReader) – Log file object opened in binary mode.

Returns

The parsed log as a

Model per line.

Return type

ASCIIInfo

Warns

ASCIIParserWarning – If the ASCII log file exited with error, see ASCIIInfo.exit_with_error for more information.

parse_line(line, lineno=0, separator=b'\t', parser=None)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

• separator (Optional[bytes]) – Data separator.

• parser (List of BaseType, required) – Field data type parsers.

Returns

The parsed log as a plain dict.

Raises

ASCIIPaserError – If parser is not provided; or failed to serialise line as ASCII.

Return type

Dict[str, Any]

zlogging.loader.parse_json(filename, parser=None, model=None, *args, **kwargs)

Parse JSON log file.

Parameters

• filename (os.PathLike) – Log file name.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed JSON log data.

Return type

zlogging._data.JSONInfo

zlogging.loader.load_json(file, parser=None, model=None, *args, **kwargs)

Parse JSON log file.

Parameters

• file (_io.BufferedReader) – Log file object opened in binary mode.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed JSON log data.

Return type

zlogging._data.JSONInfo

zlogging.loader.loads_json(data, parser=None, model=None, *args, **kwargs)

Parse JSON log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• parser (JSONParser, optional) – Parser class.

• model (Model class, optional) – Field declarations for JSONParser, as in JSON logs the field typing information are omitted by the Bro/Zeek logging framework.

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed JSON log data.

Return type

zlogging._data.JSONInfo

zlogging.loader.parse_ascii(filename, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log file.

Parameters

• filename (os.PathLike) – Log file name.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed ASCII log data.

Return type

zlogging._data.ASCIIInfo

zlogging.loader.load_ascii(file, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log file.

Parameters

• file (_io.BufferedReader) – Log file object opened in binary mode.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed ASCII log data.

Return type

zlogging._data.ASCIIInfo

zlogging.loader.loads_ascii(data, parser=None, type_hook=None, enum_namespaces=None, bare=False, *args, **kwargs)

Parse ASCII log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• parser (ASCIIParser, optional) – Parser class.

• type_hook (dict mapping str and BaseType class, optional) – Bro/Zeek type parser hooks. User may customise subclasses of BaseType to modify parsing behaviours.

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

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

• *args – Variable length argument list.

• **kwargs – Arbitrary keyword arguments.

Returns

The parsed ASCII log data.

Return type

zlogging._data.ASCIIInfo

zlogging.loader.parse(filename, *args, **kwargs)

Parse Bro/Zeek log file.

Parameters

• filename (os.PathLike) – Log file name.

• *args – See parse_json() and parse_ascii() for more information.

• **kwargs – See parse_json() and parse_ascii() for more information.

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

Return type

Union[zlogging._data.JSONInfo, zlogging._data.ASCIIInfo]

zlogging.loader.load(file, *args, **kwargs)

Parse Bro/Zeek log file.

Parameters

• file (_io.BufferedReader) – Log file object opened in binary mode.

• *args – See load_json() and load_ascii() for more information.

• **kwargs – See load_json() and load_ascii() for more information.

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

Return type

Union[zlogging._data.JSONInfo, zlogging._data.ASCIIInfo]

zlogging.loader.loads(data, *args, **kwargs)

Parse Bro/Zeek log string.

Parameters

• data (AnyStr) – Log string as binary or encoded string.

• *args – See loads_json() and loads_ascii() for more information.

• **kwargs – See loads_json() and loads_ascii() for more information.

Returns

The parsed JSON log data.

Raises

ParserError – If the format of the log file is unknown.

Return type

Union[zlogging._data.JSONInfo, zlogging._data.ASCIIInfo]

Abstract Base Loaders

class zlogging.loader.BaseParser

Bases: object

Basic log parser.

abstract property format

str: Log file format.

parse(filename)

Parse log file.

Parameters

filename (os.PathLike) – Log file name.

Returns

The parsed log as an ASCIIInfo or JSONInfo.

Return type

zlogging._data.Info

abstract parse_file(file)

Parse log file.

Parameters

file (_io.BufferedReader) – Log file object opened in binary mode.

Returns

The parsed log as a Model per line.

Return type

Info

abstract parse_line(line, lineno=0)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

Returns

The parsed log as a plain dict.

Return type

Dict[str, Any]

load(file)

Parse log file.

Parameters

file (_io.BufferedReader) – Log file object opened in binary mode.

Returns

The parsed log as a Model per line.

Return type

Info

loads(line, lineno=0)

Parse log line as one-line record.

Parameters

• line (bytes) – A simple line of log.

• lineno (Optional[int]) – Line number of current line.

Returns

The parsed log as a plain dict.

Return type

Dict[str, Any]