Audit Module

class beautifuljason.audit.AuditEntry(timestamp: datetime, level: str, source: str, message: str, message_hash: bytes, expected_hash: bytes)

Bases: object

Added in version 1.2.0.

Class representing a single entry in the JASON audit log.

property arguments: dict | str | None

Returns:: The arguments of the operation if this is a ‘before’ or ‘after’ operation entry, otherwise None. If the arguments are in JSON format, they will be parsed into a dictionary. If parsing fails, the raw string will be returned.

expected_hash: bytes: The expected SHA-256 hash of the log entry message combined with the previous log entry hash. This is calculated from the message and the previous entry hash to verify integrity.

property is_hash_valid: bool

Returns:: True if the message hash is valid, False otherwise.

False means the log entry is tampered or corrupted.

property is_operation_end: bool: True if the entry is an ‘after operation’ entry.

property is_operation_start: bool: True if the entry is a ‘before operation’ entry.

property is_single_step_operation: bool: True if the entry is an atomic operation entry.

level: str: The log level of the entry (e.g., ‘INFO’, ‘WARNING’, ‘CRITICAL’).

message: str: The message of the log entry.

message_hash: bytes: The SHA-256 hash of the log entry message combined with the previous log entry hash. This is written by JASON to ensure the integrity of the log entries.

property operation_name: str

Returns:: The name of the operation if this is a ‘before’ or ‘after’ operation entry, otherwise an empty string.

source: str: The source of the log entry (e.g., ‘application’, ‘system’).

timestamp: datetime: The timestamp of the log entry.

class beautifuljason.audit.AuditNodeXML(entry: beautifuljason.audit.AuditEntry | None, children: list['AuditNodeXML'] = <factory>)

Bases: object

children: list[AuditNodeXML]

entry: AuditEntry | None

class beautifuljason.audit.AuditTrail(logfile_path: str)

Bases: object

Added in version 1.2.0.

Class to parse JASON audit log files. This class reads a JASON audit log file, checks its integrity and provides access to its entries, metadata, and timestamps.

Parameters:: logfile_path (str) – Path to the JASON audit log file.

See also

beautifuljason.document.Document.logfile_path() for the path to the audit log file in a JASON document.

_get_metadata(source: str, key: str) → str | None

_parse()

_parse_entry(lines: list[str], prev_entry_hash: bytes) → AuditEntry | None

_starts_timestamp_line(line: str) → bool

property begin_timestamp: datetime | None

Returns:: The timestamp of the first entry if it is ‘Log start’, otherwise None, meaning the log is invalid.

property duration: float | None

Returns:: The duration of the log in seconds, or None if the log is incomplete.

property end_timestamp: datetime | None

Returns:: The timestamp of the last entry if it is ‘Log end’, otherwise None, meaning the log is incomplete.

property is_complete: bool

Returns:: True if the log is complete (ends with ‘Log end’), False otherwise.

property is_hash_valid: bool

Returns:: True if the last entry’s hash is valid, meaning the log entries are not tampered with.

property jason_version

Returns:: The JASON version which was used to create the log file.

property os

Returns:: The operating system information from the audit log.

property os_user

Returns:: The operating system user from the audit log.

property qt_version

Returns:: The Qt version used by JASON.

class beautifuljason.audit.AuditTrailXMLExporter(audit_trail: AuditTrail)

Bases: object

Added in version 1.2.0.

Class for converting JASON audit trails to XML format. Intended for reporting and analysis purposes. It is recommended to store the audit trail in the original JASON log file format to ensure integrity and completeness.

Parameters:: audit_trail (AuditTrail) – The JASON audit trail to export.

_build_audit_tree() → AuditNodeXML: Build a tree structure from the audit entries to represent operations and their contexts. This method organizes the audit entries into a tree structure where each node represents an operation and its children represent the log entries within that operation’s context. The root node is a dummy node that does not correspond to any log entry. The tree structure allows for easy traversal and export to XML.

_build_etree() → Element: Construct the XML root element from the audit trail.

_default_xslt() → str

_dict_to_xml(parent: Element, data: dict)

Convert a dictionary to XML elements recursively. This method creates XML elements for each key-value pair in the dictionary. If the value is a dictionary, it recurses into that dictionary. If the value is a list, it creates an ‘item’ element for each item in the list. If the value is None, it skips that key. If the value is a simple type (str, int, etc.), it sets the text of the element. :param parent: The parent XML element to append to. :param data: The dictionary to convert to XML.

_entry_attributes(entry: AuditEntry) → dict: Extract attributes from an AuditEntry for XML representation. This method returns a dictionary of attributes that will be used in the XML element. :param entry: The AuditEntry to extract attributes from. :type entry: AuditEntry :return: A dictionary of attributes for the XML element. :rtype: dict

_render_arguments(entry: AuditEntry, state: str) → Element | None

_render_xml_node(node: AuditNodeXML) → Element

_sanitize_xml_tag(tag: str) → str

save_html(html_path: str, xslt_str: str | None = None)

Transform the audit trail XML into HTML using an XSLT stylesheet and save it to a file.

Parameters:

html_path – Path to the output HTML file.
xslt_str – Optional XSLT stylesheet string. If None, a default one is used.

save_xml(path: str): Save the XML representation of the audit trail to a file. :param path: The file path to save the XML to. :type path: str