midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/__init__.py

@@ -0,0 +1,234 @@
+import getpass
+import importlib
+import importlib.metadata
+import logging
+import os
+import shlex
+import sys
+from argparse import REMAINDER, ArgumentParser, ArgumentTypeError, RawTextHelpFormatter
+
+from midpoint_cli.client import MidpointClient
+from midpoint_cli.client.session import (
+    READ_TIMEOUT_ENV_VAR,
+    READ_TIMEOUT_SECONDS,
+    RETRY_TIMEOUT_ENV_VAR,
+    RETRY_TIMEOUT_SECONDS,
+    parse_retry_timeout,
+)
+from midpoint_cli.prompt import MidpointClientPrompt
+from midpoint_cli.prompt.configuration import (
+    CONFIGURATION_FILE_VARIABLE,
+    SOURCE_DEFAULT,
+    ConfigurationFileError,
+    ResolvedConfiguration,
+    configuration_file_permission_warning,
+    ignored_working_directory_file,
+    is_unencrypted_remote_url,
+    load_configuration_file,
+    locate_configuration_file,
+    resolve_client_configuration,
+)
+from midpoint_cli.prompt.console import OUTPUT_FORMATS, ConsoleDisplay, default_output_format, print_info
+
+
+def _build_commands_epilog(version: str) -> str:
+    skip = {'EOF', 'exit'}
+    commands = []
+    for name in sorted(dir(MidpointClientPrompt)):
+        if name.startswith('do_'):
+            cmd = name[3:]
+            if cmd in skip:
+                continue
+            method = getattr(MidpointClientPrompt, name)
+            doc = method.__doc__.strip().splitlines()[0] if method.__doc__ else ''
+            commands.append((cmd, doc))
+
+    if not commands:
+        return ''
+
+    width = max(len(cmd) for cmd, _ in commands) + 2
+    lines = ['', 'Available commands:']
+    for cmd, doc in commands:
+        lines.append(f'  {cmd:<{width}}{doc}')
+
+    lines += [
+        '',
+        'Server URL and credentials can also be stored in ~/.midpoint-cli.cfg, or in a file',
+        'named with --config or MIDPOINT_CLI_CONFIG, or read from environment variables',
+        'MIDPOINT_URL, MIDPOINT_USERNAME and MIDPOINT_PASSWORD.',
+        'Prefer those, or -P, over -p: a password given on the command line is visible to other users.',
+        f'The retry timeout (--timeout) can also be set with {RETRY_TIMEOUT_ENV_VAR} or a timeout',
+        f'key in the configuration file; it defaults to {RETRY_TIMEOUT_SECONDS:g} seconds.',
+        f'The read timeout (--read-timeout) can also be set with {READ_TIMEOUT_ENV_VAR} or a',
+        f'read_timeout key in the configuration file; it defaults to {READ_TIMEOUT_SECONDS:g} seconds.',
+        '',
+        f'Midpoint-cli version {version}, created and maintained by Yannick Kirschhoffer alcibiade@alcibiade.org',
+        '',
+    ]
+    return '\n'.join(lines)
+
+
+def _positive_seconds(raw: str) -> float:
+    """argparse type for --timeout and --read-timeout: a finite positive number of seconds."""
+    value = parse_retry_timeout(raw)
+    if value is None:
+        raise ArgumentTypeError(f'expected a positive number of seconds, got {raw!r}')
+    return value
+
+
+def _print_configuration_banner(resolved: ResolvedConfiguration, config_path: str | None) -> None:
+    """Tell an interactive user which server and account the session uses, and where they came from."""
+    print_info(resolved.describe())
+    ignored_file = ignored_working_directory_file(config_path)
+    if ignored_file is not None:
+        print_info(f'{ignored_file} in the working directory is not read; use --config {ignored_file} to read it.')
+
+
+def _missing_password_message(config_path: str | None) -> str:
+    message = (
+        'no password configured. Use -P to be prompted for it, set MIDPOINT_PASSWORD, '
+        'or add a password to the configuration file'
+    )
+    message += f' ({config_path}).' if config_path else ' (~/.midpoint-cli.cfg or --config PATH).'
+    ignored_file = ignored_working_directory_file(config_path)
+    if ignored_file is not None:
+        message += f' {ignored_file} in the working directory is not read; use --config {ignored_file} to read it.'
+    return message
+
+
+def main():
+    logging.basicConfig(level=logging.INFO)
+    logging.getLogger('urllib3.connectionpool').setLevel(logging.ERROR)
+
+    version = importlib.metadata.version('midpoint_cli')
+
+    MIDPOINT_ENVIRONMENT_VARS = [
+        'MIDPOINT_URL',
+        'MIDPOINT_USERNAME',
+        'MIDPOINT_PASSWORD',
+        RETRY_TIMEOUT_ENV_VAR,
+        READ_TIMEOUT_ENV_VAR,
+    ]
+
+    argument_parser = ArgumentParser(
+        description='An interactive Midpoint command line client.',
+        formatter_class=RawTextHelpFormatter,
+        epilog=_build_commands_epilog(version),
+        # Without this, `audit ls --user X` matched --username by prefix.
+        allow_abbrev=False,
+    )
+    argument_parser.add_argument('-v', '--version', help='Show version information and exit.', action='store_true')
+    argument_parser.add_argument(
+        '-u', '--username', help='Set the username to authenticate this session.', default=None
+    )
+    argument_parser.add_argument(
+        '-p', '--password', help='Set the password to authenticate this session.', default=None
+    )
+    argument_parser.add_argument(
+        '-P',
+        '--ask-password',
+        help='Prompt for the password instead of passing it on the command line,\n'
+        'where it would be visible in the process list and the shell history.',
+        action='store_true',
+    )
+    argument_parser.add_argument('-U', '--url', help='Midpoint base URL', default=None)
+    argument_parser.add_argument(
+        '-t',
+        '--timeout',
+        metavar='SECONDS',
+        type=_positive_seconds,
+        help=f'Keep retrying a request the server does not answer for up to SECONDS\n'
+        f'(default: {RETRY_TIMEOUT_ENV_VAR}, then the configuration file, then {RETRY_TIMEOUT_SECONDS:g}).',
+        default=None,
+    )
+    argument_parser.add_argument(
+        '--read-timeout',
+        metavar='SECONDS',
+        type=_positive_seconds,
+        help=f'Wait up to SECONDS for the answer to each request; a read timeout is not retried\n'
+        f'(default: {READ_TIMEOUT_ENV_VAR}, then the configuration file, then {READ_TIMEOUT_SECONDS:g}).',
+        default=None,
+    )
+    argument_parser.add_argument(
+        '-c',
+        '--config',
+        metavar='PATH',
+        help=f'Read settings from this configuration file instead of ~/.midpoint-cli.cfg.\n'
+        f'Defaults to the {CONFIGURATION_FILE_VARIABLE} environment variable when set.',
+        default=None,
+    )
+    argument_parser.add_argument(
+        '-o',
+        '--output',
+        choices=OUTPUT_FORMATS,
+        help='Output format of list commands (ls, search, users, tasks, ...) and of the\n'
+        'user, role, org and task get details: a table, or json, csv or tsv for scripts.\n'
+        'Defaults to table on a terminal and to tsv when the output is redirected or piped.\n'
+        'The output command changes it during a session.',
+        default=None,
+    )
+    argument_parser.add_argument('command', help='Optional command to be executed immediately.', nargs='?')
+    # REMAINDER stops top-level option parsing at the command word, so every flag
+    # after it (`put -p patch.xml`, `audit ls --user X`, `task run --no-changes`)
+    # belongs to the command instead of being taken as a global option.
+    argument_parser.add_argument('arg', help='Optional command arguments.', nargs=REMAINDER)
+
+    argument_namespace = argument_parser.parse_args(sys.argv[1:])
+
+    if argument_namespace.version:
+        print(f'Midpoint CLI Version {version}')
+        sys.exit(0)
+
+    if argument_namespace.ask_password:
+        argument_namespace.password = getpass.getpass('Midpoint password: ')
+
+    config_path, _ = locate_configuration_file(argument_namespace.config, os.getenv(CONFIGURATION_FILE_VARIABLE))
+    try:
+        config_parser = load_configuration_file(config_path)
+        resolved_configuration = resolve_client_configuration(
+            argument_namespace, config_parser, [os.getenv(v) for v in MIDPOINT_ENVIRONMENT_VARS], config_path
+        )
+    except ConfigurationFileError as e:
+        argument_parser.exit(2, f'{argument_parser.prog}: error: {e}\n')
+    if resolved_configuration.sources['password'] == SOURCE_DEFAULT:
+        # Fail closed rather than silently trying the Midpoint demo password.
+        if sys.stdin.isatty() and not argument_namespace.ask_password:
+            resolved_configuration.set('password', getpass.getpass('Midpoint password: '), 'password prompt')
+        if resolved_configuration.sources['password'] == SOURCE_DEFAULT:
+            argument_parser.exit(2, f'{argument_parser.prog}: error: {_missing_password_message(config_path)}\n')
+
+    client_configuration = resolved_configuration.configuration
+
+    permission_warning = configuration_file_permission_warning(config_path, config_parser, client_configuration.url)
+    if permission_warning is not None:
+        logging.getLogger(__name__).warning(permission_warning)
+
+    if is_unencrypted_remote_url(client_configuration.url):
+        logging.getLogger(__name__).warning(
+            'Credentials will be sent with HTTP Basic authentication over unencrypted http:// to %s. '
+            'Use an https:// server URL unless the server is on a trusted network.',
+            client_configuration.url,
+        )
+
+    client = MidpointClient(client_configuration, observer=ConsoleDisplay())
+    prompt = MidpointClientPrompt(
+        client,
+        resolved_configuration,
+        output_format=argument_namespace.output or default_output_format(),
+    )
+
+    if argument_namespace.command is not None:
+        parts = [argument_namespace.command, *argument_namespace.arg]
+        prompt.onecmd(' '.join(shlex.quote(p) for p in parts))
+        sys.exit(prompt.error_code)
+    else:
+        if sys.stdin.isatty():
+            _print_configuration_banner(resolved_configuration, config_path)
+        prompt.cmdloop()
+        if not sys.stdin.isatty():
+            # Commands piped on stdin form a script: fail it with the code of its first failed line.
+            sys.exit(prompt.first_error_code)
+
+
+if __name__ == '__main__':
+    main()

midpoint_cli/client/__init__.py

@@ -0,0 +1,199 @@
+"""Midpoint client package: the public names scripts and the CLI import from ``midpoint_cli.client``.
+
+The code lives in focused modules; this package re-exports their public names:
+
+- ``midpoint_client``: ``MidpointClient``, the high-level operations;
+- ``rest``: ``RestApiClient``, the REST transport, and ``PutResult``;
+- ``configuration``: ``MidpointClientConfiguration``;
+- ``errors``: the exceptions;
+- ``audit``: audit search support (``AUDIT_CURSOR_CLOCK_MARGIN``);
+- ``objects``: the object types (``MidpointObjectTypes``) and the parsed objects;
+- the helper modules (``object_query``, ``audit_query``, ``server_version``, ``server_info``,
+  ``logging_config``, ``task_definitions``, ``session``, ``progress``, ``observer``, ``patch``,
+  ``safe_xml``), whose names are re-exported as before.
+"""
+
+from midpoint_cli.client.audit import AUDIT_CURSOR_CLOCK_MARGIN
+from midpoint_cli.client.audit_query import AUDIT_EXEC_SCRIPT_PATH, AuditQuery, build_execute_script_body
+from midpoint_cli.client.configuration import MidpointClientConfiguration
+from midpoint_cli.client.errors import (
+    MidpointAmbiguousName,
+    MidpointAuditScriptIncompatible,
+    MidpointAuditScriptRefused,
+    MidpointClientNotConfigured,
+    MidpointInvalidOid,
+    MidpointMissingPassword,
+    MidpointObjectNotFound,
+    MidpointServerError,
+    MidpointUnsupportedOperation,
+    TaskExecutionFailure,
+)
+from midpoint_cli.client.logging_config import (
+    LoggingConfiguration,
+    check_logger_name,
+    class_logger_modification,
+    normalize_level,
+    parse_logging,
+)
+from midpoint_cli.client.midpoint_client import (
+    SHADOW_SITUATIONS,
+    TASK_START_ATTEMPTS,
+    TASK_START_POLL_SECONDS,
+    MidpointClient,
+)
+from midpoint_cli.client.object_query import (
+    ORG_SEARCH_PATHS,
+    ROLE_SEARCH_PATHS,
+    USER_SEARCH_PATHS,
+    ObjectQuery,
+    and_filter,
+    equal_filter,
+    in_oid_filter,
+    is_oid,
+    ref_filter,
+    task_status_filter,
+)
+from midpoint_cli.client.objects import (
+    MidpointAuditEvent,
+    MidpointConnector,
+    MidpointObject,
+    MidpointObjectList,
+    MidpointObjectType,
+    MidpointObjectTypes,
+    MidpointOrganization,
+    MidpointResource,
+    MidpointRole,
+    MidpointShadow,
+    MidpointTask,
+    MidpointUser,
+    namespaces,
+    safe_get_text,
+)
+from midpoint_cli.client.observer import MidpointCommunicationObserver, NopMidpointCommunicationObserver
+from midpoint_cli.client.patch import patch_from_file
+from midpoint_cli.client.progress import NopProgressMonitor, ProgressMonitor
+from midpoint_cli.client.rest import CONNECT_TIMEOUT_SECONDS, TOTAL_COUNT_HEADER, PutResult, RestApiClient
+from midpoint_cli.client.safe_xml import fromstring as safe_fromstring
+from midpoint_cli.client.server_info import (
+    ACTUATOR_FIELDS,
+    SYSTEM_CONFIGURATION_OID,
+    ServerInformation,
+    describe_repository,
+    parse_deployment,
+    parse_logged_in_user,
+    parse_nodes,
+)
+from midpoint_cli.client.server_version import (
+    MidpointVersion,
+    describe_version,
+    groovy_refused_by_default,
+    parse_server_version,
+)
+from midpoint_cli.client.session import (
+    READ_TIMEOUT_ENV_VAR,
+    RETRY_TIMEOUT_ENV_VAR,
+    CustomHTTPAdapter,
+    CustomRetryManager,
+    read_timeout_seconds,
+    retry_attempts_for,
+    retry_timeout_seconds,
+)
+from midpoint_cli.client.task_definitions import (
+    report_task_name,
+    report_task_xml,
+    resource_task_name,
+    resource_task_xml,
+)
+
+# Grouped by topic under comments rather than sorted, so RUF022 does not apply.
+__all__ = [  # noqa: RUF022
+    # Client, transport and configuration
+    'MidpointClient',
+    'RestApiClient',
+    'MidpointClientConfiguration',
+    'PutResult',
+    'CONNECT_TIMEOUT_SECONDS',
+    'TOTAL_COUNT_HEADER',
+    'SHADOW_SITUATIONS',
+    'TASK_START_ATTEMPTS',
+    'TASK_START_POLL_SECONDS',
+    'AUDIT_CURSOR_CLOCK_MARGIN',
+    # Exceptions
+    'MidpointServerError',
+    'MidpointUnsupportedOperation',
+    'MidpointInvalidOid',
+    'MidpointObjectNotFound',
+    'MidpointAmbiguousName',
+    'MidpointMissingPassword',
+    'MidpointClientNotConfigured',
+    'MidpointAuditScriptRefused',
+    'MidpointAuditScriptIncompatible',
+    'TaskExecutionFailure',
+    # Object types and parsed objects
+    'MidpointObjectType',
+    'MidpointObjectTypes',
+    'MidpointObject',
+    'MidpointObjectList',
+    'MidpointUser',
+    'MidpointRole',
+    'MidpointOrganization',
+    'MidpointResource',
+    'MidpointConnector',
+    'MidpointShadow',
+    'MidpointTask',
+    'MidpointAuditEvent',
+    'namespaces',
+    'safe_get_text',
+    # Queries
+    'ObjectQuery',
+    'AuditQuery',
+    'AUDIT_EXEC_SCRIPT_PATH',
+    'build_execute_script_body',
+    'USER_SEARCH_PATHS',
+    'ROLE_SEARCH_PATHS',
+    'ORG_SEARCH_PATHS',
+    'and_filter',
+    'equal_filter',
+    'in_oid_filter',
+    'is_oid',
+    'ref_filter',
+    'task_status_filter',
+    # Server version and information
+    'MidpointVersion',
+    'describe_version',
+    'groovy_refused_by_default',
+    'parse_server_version',
+    'ServerInformation',
+    'ACTUATOR_FIELDS',
+    'SYSTEM_CONFIGURATION_OID',
+    'describe_repository',
+    'parse_deployment',
+    'parse_logged_in_user',
+    'parse_nodes',
+    # Logging configuration
+    'LoggingConfiguration',
+    'check_logger_name',
+    'class_logger_modification',
+    'normalize_level',
+    'parse_logging',
+    # Tasks created by the CLI
+    'report_task_name',
+    'report_task_xml',
+    'resource_task_name',
+    'resource_task_xml',
+    # Progress and communication monitoring
+    'ProgressMonitor',
+    'NopProgressMonitor',
+    'MidpointCommunicationObserver',
+    'NopMidpointCommunicationObserver',
+    # HTTP session, XML and patch helpers
+    'CustomHTTPAdapter',
+    'CustomRetryManager',
+    'READ_TIMEOUT_ENV_VAR',
+    'RETRY_TIMEOUT_ENV_VAR',
+    'read_timeout_seconds',
+    'retry_attempts_for',
+    'retry_timeout_seconds',
+    'safe_fromstring',
+    'patch_from_file',
+]

midpoint_cli/client/audit.py

@@ -0,0 +1,178 @@
+"""Audit search support: parsing the executeScript answer and explaining refused or failing scripts."""
+
+import logging
+import re
+from datetime import UTC, datetime, timedelta
+from xml.etree import ElementTree
+
+from midpoint_cli.client.constants import API_TYPES_NS, AUDIT_NS, COMMON_NS, SCRIPTING_NS, ResultStatus
+from midpoint_cli.client.errors import (
+    MidpointAuditScriptIncompatible,
+    MidpointAuditScriptRefused,
+    MidpointServerError,
+)
+from midpoint_cli.client.objects import MidpointAuditEvent
+from midpoint_cli.client.safe_xml import fromstring as safe_fromstring
+from midpoint_cli.client.server_version import MidpointVersion, describe_version, groovy_refused_by_default
+
+logger = logging.getLogger(__name__)
+
+
+# Midpoint 4.11 runs two independent checks before executing a Groovy script. The safety
+# check runs first and hides the profile check, so a refusal always lists both settings.
+_AUDIT_SCRIPT_REFUSAL_CHECKS = {
+    'is not considered safe': 'config.xml safety check',
+    'is not allowed in expression profile': 'expression profile check',
+}
+_AUDIT_SCRIPT_REFUSAL_HELP = (
+    'Audit search runs a Groovy script on the server, which Midpoint 4.11+ refuses by default '
+    '({server} blocked it with the {check}). To enable it: '
+    '(1) set midpoint/expressions/safeScriptingLanguagesOnly to false in config.xml and restart Midpoint, '
+    'unless config.xml has no such setting; '
+    '(2) add an expression profile allowing Groovy to the system configuration (expressions/expressionProfile) '
+    'and reference it from expressions/defaults/privilegedPrincipal.'
+)
+
+
+def _audit_script_refusal_check(error_message: str) -> str | None:
+    """Name the server check that refused the Groovy script in an executeScript error, or None for other errors."""
+    if 'Groovy' not in error_message:
+        return None
+    for marker, check in _AUDIT_SCRIPT_REFUSAL_CHECKS.items():
+        if marker in error_message:
+            return check
+    return None
+
+
+# Error texts of a script that does not fit the server, as Midpoint 4.8.14 reports them: a compile
+# error ("Compilation error ... unable to resolve class X"), an API change ("No signature of
+# method ..."), or a class missing at run time, reported as the bare class name.
+_AUDIT_SCRIPT_COMPILE_MARKERS = ('Compilation error', 'unable to resolve class')
+_AUDIT_SCRIPT_LINKAGE_MARKERS = (
+    'ClassNotFoundException',
+    'NoClassDefFoundError',
+    'No signature of method',
+    'MissingMethodException',
+    'No such property',
+    'MissingPropertyException',
+)
+_AUDIT_SCRIPT_MISSING_CLASS = re.compile(r": (?:[a-z_$][\w$]*[./])+[A-Z][\w$]* in (?:in )?'execute-script'")
+_AUDIT_SCRIPT_INCOMPATIBLE_HELP = (
+    'Audit search failed on {server}: the Groovy script it runs on the server {problem}. The script relies on '
+    'Midpoint-internal classes (SpringApplicationContextHolder, AuditService, PrismContext) that may have moved '
+    'or changed in this version; midpoint-cli supports Midpoint 4.4 to 4.11. Server error: {error}'
+)
+
+
+def _audit_script_incompatibility(error_message: str) -> str | None:
+    """Describe a compile or linkage failure of the audit script, or None for other errors."""
+    if any(marker in error_message for marker in _AUDIT_SCRIPT_COMPILE_MARKERS):
+        return 'could not be compiled'
+    if any(marker in error_message for marker in _AUDIT_SCRIPT_LINKAGE_MARKERS) or (
+        _AUDIT_SCRIPT_MISSING_CLASS.search(error_message) is not None
+    ):
+        return "does not match the server's internal classes"
+    return None
+
+
+def audit_script_error(
+    error: MidpointServerError, server_version: MidpointVersion | None
+) -> MidpointServerError | None:
+    """The clearer error to raise instead of error when the server refused or could not run the audit script.
+
+    Returns MidpointAuditScriptRefused (only for servers that refuse Groovy by default, so the
+    errors of earlier versions are never read as a refusal), MidpointAuditScriptIncompatible,
+    or None when error is about something else.
+    """
+    server = describe_version(server_version)
+    check = _audit_script_refusal_check(str(error)) if groovy_refused_by_default(server_version) else None
+    if check is not None:
+        return MidpointAuditScriptRefused(_AUDIT_SCRIPT_REFUSAL_HELP.format(check=check, server=server))
+    problem = _audit_script_incompatibility(str(error))
+    if problem is not None:
+        return MidpointAuditScriptIncompatible(
+            _AUDIT_SCRIPT_INCOMPATIBLE_HELP.format(server=server, problem=problem, error=error)
+        )
+    return None
+
+
+# How far the audit cursor of a run triggered by the CLI starts before the client's
+# clock, so that a client clock ahead of the server's does not hide the run's first events.
+AUDIT_CURSOR_CLOCK_MARGIN = timedelta(seconds=60)
+
+
+def as_utc(dt: datetime) -> datetime:
+    """Make a datetime aware, reading a naive one as UTC (MidpointTask parses 'Z' timestamps as naive)."""
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=UTC)
+
+
+def initial_audit_cursor(run_started_at: datetime | None, task_start_time: datetime | None) -> datetime | None:
+    """Pick where audit streaming starts for ``task_wait``.
+
+    Without ``run_started_at`` the cursor is the task's last run start, a server timestamp.
+    ``run_started_at`` comes from the client clock, so it is moved back by
+    ``AUDIT_CURSOR_CLOCK_MARGIN``. The task's last run start, read after the run was
+    triggered, is never later than the events of this run, so it can only narrow that window.
+    """
+    task_start = as_utc(task_start_time) if task_start_time is not None else None
+    if run_started_at is None:
+        return task_start
+    cursor = as_utc(run_started_at) - AUDIT_CURSOR_CLOCK_MARGIN
+    if task_start is not None and task_start > cursor:
+        return task_start
+    return cursor
+
+
+def parse_audit_timestamp(text: str) -> datetime | None:
+    """Parse an audit-event ISO-8601 timestamp into an aware UTC datetime."""
+    iso = text.strip()
+    if iso.endswith('Z'):
+        iso = iso[:-1] + '+00:00'
+    try:
+        dt = datetime.fromisoformat(iso)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC)
+
+
+def parse_audit_events_from_script_response(response_xml: str) -> list:
+    """Extract MidpointAuditEvent records from an executeScript response.
+
+    The Groovy script returns a string containing concatenated
+    ``<aud:auditEventRecord>`` elements wrapped in a parent. Midpoint
+    serializes that as one ``<s:value xsi:type="xsd:string">`` per pipeline
+    item; the inner XML arrives HTML-escaped inside the string.
+    """
+    tree = safe_fromstring(response_xml)
+
+    status = tree.find(f'{{{COMMON_NS}}}status')
+    if status is None:
+        # When wrapped in apti:ExecuteScriptResponseType, the result is at apti:result/c:status
+        status = tree.find(f'{{{API_TYPES_NS}}}result/{{{COMMON_NS}}}status')
+    if status is not None and status.text == ResultStatus.FATAL_ERROR:
+        msg = tree.find(f'{{{COMMON_NS}}}message')
+        if msg is None:
+            msg = tree.find(f'{{{API_TYPES_NS}}}result/{{{COMMON_NS}}}message')
+        raise MidpointServerError(msg.text if msg is not None and msg.text else 'audit search failed')
+
+    events: list = []
+    for value_node in tree.iter(f'{{{SCRIPTING_NS}}}value'):
+        text = value_node.text
+        if not text or '<aud:auditEventRecord' not in text:
+            continue
+        # ElementTree already decoded character entities — text is real XML.
+        # Re-wrap to ensure a single root, in case the embedded namespace
+        # prefixes aren't bound on the new root (the Groovy wrapper already
+        # produces a single <auditEventRecords> root, but defend against
+        # future shape changes).
+        wrapped = f'<auditEventRecords xmlns:aud="{AUDIT_NS}" xmlns:c="{COMMON_NS}">{text}</auditEventRecords>'
+        try:
+            inner = safe_fromstring(wrapped)
+        except ElementTree.ParseError as e:
+            logger.warning('Skipping malformed audit record payload: %s', e)
+            continue
+        for record in inner.iter(f'{{{AUDIT_NS}}}auditEventRecord'):
+            events.append(MidpointAuditEvent(record))
+    return events