midpoint-cli 1.6.0.dev3__py3-none-any.whl

midpoint_cli/client/audit_query.py

@@ -0,0 +1,247 @@
+"""Audit query construction for Midpoint REST audit search.
+
+Midpoint (up to 4.11 at least) does not expose a dedicated REST endpoint for
+audit search. We tunnel the search through the bulk-actions ``executeScript``
+endpoint: a tiny Groovy snippet looks up the ``AuditService`` Spring bean, parses
+the QueryType XML built here, runs ``searchObjects``, and returns each
+record as a serialized XML string. The CLI then decodes that string and
+parses each ``<aud:auditEventRecord>`` back into ``MidpointAuditEvent``.
+
+Midpoint 4.11 made MEL the default script language and denies Groovy to every
+expression profile out of the box, and MEL cannot reach the audit service. The
+script therefore names Groovy explicitly, and 4.11 servers must opt in to it.
+
+The script uses Midpoint-internal classes, not a public API, so a release that
+moves or changes them breaks it: the client reports such compile and linkage
+errors with the server version (see ``MidpointAuditScriptIncompatible``).
+"""
+
+import base64
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from xml.sax.saxutils import escape as xml_escape
+
+from midpoint_cli.client.constants import COMMON_NS, QUERY_NS, SCRIPTING_NS
+from midpoint_cli.client.server_version import MidpointVersion, audit_context_holder_class
+
+AUDIT_EXEC_SCRIPT_PATH = 'ws/rest/rpc/executeScript'
+GROOVY_LANGUAGE_URI = 'http://midpoint.evolveum.com/xml/ns/public/expression/language#Groovy'
+
+_DURATION_RE = re.compile(r'^\s*(\d+)\s*([smhdw])\s*$', re.IGNORECASE)
+_UNIT_SECONDS = {'s': 1, 'm': 60, 'h': 3600, 'd': 86400, 'w': 604800}
+
+
+def parse_duration(spec: str) -> datetime:
+    """Resolve a duration spec or absolute ISO-8601 timestamp to an aware UTC datetime.
+
+    Relative forms ``Ns``/``Nm``/``Nh``/``Nd``/``Nw`` are subtracted from now.
+    """
+    if not spec:
+        raise ValueError('Empty duration specification')
+
+    match = _DURATION_RE.match(spec)
+    if match:
+        value = int(match.group(1))
+        unit = match.group(2).lower()
+        delta = timedelta(seconds=value * _UNIT_SECONDS[unit])
+        return datetime.now(UTC) - delta
+
+    iso = spec.strip()
+    if iso.endswith('Z'):
+        iso = iso[:-1] + '+00:00'
+    try:
+        dt = datetime.fromisoformat(iso)
+    except ValueError as exc:
+        raise ValueError(
+            f'Invalid duration or timestamp: {spec!r}. Expected forms like "1h", "30m", "2d", "1w" '
+            'or an ISO-8601 timestamp such as "2026-05-09T08:00:00Z".'
+        ) from exc
+
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC)
+
+
+def _format_xsd_datetime(dt: datetime) -> str:
+    aware = dt if dt.tzinfo is not None else dt.replace(tzinfo=UTC)
+    aware = aware.astimezone(UTC)
+    return aware.strftime('%Y-%m-%dT%H:%M:%S.') + f'{aware.microsecond // 1000:03d}Z'
+
+
+@dataclass
+class AuditQuery:
+    """Filter parameters for an audit search request.
+
+    ``since`` is exclusive (``q:greater``) unless ``since_inclusive`` is set, which
+    switches it to ``q:greaterOrEqual``. Streaming cursors need the inclusive form:
+    an event committed later with the same timestamp as the newest one already
+    seen must still match, and the caller drops the repeats by event identifier.
+    """
+
+    since: datetime | None = None
+    since_inclusive: bool = False
+    until: datetime | None = None
+    initiator_oid: str | None = None
+    target_oid: str | None = None
+    target_type: str | None = None
+    channel: str | None = None
+    outcome: str | None = None
+    event_type: str | None = None
+    event_stage: str | None = None
+    event_identifier: str | None = None
+    task_identifier: str | None = None
+    limit: int = 50
+    _equal_filters: list[tuple[str, str]] = field(default_factory=list, init=False, repr=False)
+
+    def to_xml(self) -> str:
+        """Render the query as a Midpoint ``<q:query>`` XML document."""
+        filters: list[str] = []
+
+        if self.since is not None:
+            since = _format_xsd_datetime(self.since)
+            if self.since_inclusive:
+                filters.append(self._greater_or_equal_filter('timestamp', since))
+            else:
+                filters.append(self._greater_filter('timestamp', since))
+        if self.until is not None:
+            filters.append(self._less_filter('timestamp', _format_xsd_datetime(self.until)))
+        if self.event_identifier is not None:
+            filters.append(self._equal_filter('eventIdentifier', self.event_identifier))
+        if self.task_identifier is not None:
+            filters.append(self._equal_filter('taskIdentifier', self.task_identifier))
+        if self.event_type is not None:
+            filters.append(self._equal_filter('eventType', self.event_type))
+        if self.event_stage is not None:
+            filters.append(self._equal_filter('eventStage', self.event_stage))
+        if self.channel is not None:
+            filters.append(self._equal_filter('channel', self.channel))
+        if self.outcome is not None:
+            filters.append(self._equal_filter('outcome', self.outcome))
+        if self.initiator_oid is not None:
+            filters.append(self._ref_filter('initiatorRef', self.initiator_oid))
+        if self.target_oid is not None:
+            filters.append(self._ref_filter('targetRef', self.target_oid, self.target_type))
+        elif self.target_type is not None:
+            filters.append(self._ref_filter('targetRef', None, self.target_type))
+
+        for path, value in self._equal_filters:
+            filters.append(self._equal_filter(path, value))
+
+        if not filters:
+            filter_block = ''
+        elif len(filters) == 1:
+            filter_block = f'<q:filter>{filters[0]}</q:filter>'
+        else:
+            filter_block = '<q:filter><q:and>' + ''.join(filters) + '</q:and></q:filter>'
+
+        if self.limit and self.limit > 0:
+            paging = (
+                '<q:paging>'
+                f'<q:maxSize>{int(self.limit)}</q:maxSize>'
+                '<q:orderBy>timestamp</q:orderBy>'
+                '<q:orderDirection>descending</q:orderDirection>'
+                '</q:paging>'
+            )
+        else:
+            paging = (
+                '<q:paging><q:orderBy>timestamp</q:orderBy><q:orderDirection>descending</q:orderDirection></q:paging>'
+            )
+
+        return f'<q:query xmlns:q="{QUERY_NS}" xmlns:c="{COMMON_NS}">{filter_block}{paging}</q:query>'
+
+    @staticmethod
+    def _equal_filter(path: str, value: str) -> str:
+        return f'<q:equal><q:path>{path}</q:path><q:value>{xml_escape(value)}</q:value></q:equal>'
+
+    @staticmethod
+    def _greater_filter(path: str, value: str) -> str:
+        return f'<q:greater><q:path>{path}</q:path><q:value>{xml_escape(value)}</q:value></q:greater>'
+
+    @staticmethod
+    def _greater_or_equal_filter(path: str, value: str) -> str:
+        return f'<q:greaterOrEqual><q:path>{path}</q:path><q:value>{xml_escape(value)}</q:value></q:greaterOrEqual>'
+
+    @staticmethod
+    def _less_filter(path: str, value: str) -> str:
+        return f'<q:less><q:path>{path}</q:path><q:value>{xml_escape(value)}</q:value></q:less>'
+
+    @staticmethod
+    def _ref_filter(path: str, oid: str | None, type_name: str | None = None) -> str:
+        attrs = ''
+        if oid:
+            attrs += f' oid="{xml_escape(oid, {chr(34): "&quot;"})}"'
+        if type_name:
+            attrs += f' type="c:{xml_escape(type_name, {chr(34): "&quot;"})}"'
+        return f'<q:ref><q:path>{path}</q:path><q:value{attrs}/></q:ref>'
+
+
+_GROOVY_TEMPLATE = """\
+import com.evolveum.midpoint.audit.api.AuditService
+import com.evolveum.midpoint.schema.result.OperationResult
+import com.evolveum.midpoint.prism.PrismContext
+import com.evolveum.midpoint.xml.ns._public.common.audit_3.AuditEventRecordType
+import com.evolveum.prism.xml.ns._public.query_3.QueryType
+import __CONTEXT_HOLDER_CLASS__
+import javax.xml.namespace.QName
+import java.nio.charset.StandardCharsets
+import java.util.Base64
+
+def QUERY_XML = new String(Base64.getDecoder().decode('__QUERY_B64__'), StandardCharsets.UTF_8)
+def ctx = SpringApplicationContextHolder.getApplicationContext()
+def audit = ctx.getBean(AuditService)
+def prismCtx = ctx.getBean(PrismContext)
+def result = new OperationResult("midpoint-cli-audit-search")
+def queryType = prismCtx.parserFor(QUERY_XML).xml().parseRealValue(QueryType.class)
+def query = prismCtx.getQueryConverter().createObjectQuery(AuditEventRecordType.class, queryType)
+def records = audit.searchObjects(query, null, result)
+def serializer = prismCtx.xmlSerializer()
+def buf = new StringBuilder()
+buf.append("<auditEventRecords>")
+records.each { r ->
+    buf.append(serializer.serializeRealValue(r,
+        new QName("http://midpoint.evolveum.com/xml/ns/public/common/audit-3", "auditEventRecord")))
+}
+buf.append("</auditEventRecords>")
+return buf.toString()
+"""
+
+
+def build_execute_script_body(query: AuditQuery, server_version: MidpointVersion | None = None) -> str:
+    """Wrap the AuditQuery in the Groovy ``executeScript`` envelope used by the CLI.
+
+    Filter values come from the command line and may contain anything, so the
+    query XML never appears in the Groovy source: it is embedded as a base64
+    string, whose alphabet cannot close a Groovy literal or the surrounding
+    CDATA section, and decoded on the server. The Midpoint-internal class used
+    to reach the Spring context moved in 4.5, so the import follows the server
+    version (the 4.5+ location when the version is unknown).
+    """
+    query_b64 = base64.b64encode(query.to_xml().encode('utf-8')).decode('ascii')
+    groovy = _GROOVY_TEMPLATE.replace('__CONTEXT_HOLDER_CLASS__', audit_context_holder_class(server_version))
+    groovy = groovy.replace('__QUERY_B64__', query_b64)
+
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>'
+        f'<s:executeScript xmlns:s="{SCRIPTING_NS}"'
+        f' xmlns:c="{COMMON_NS}"'
+        ' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'
+        '<s:pipeline>'
+        '<s:action>'
+        '<s:type>execute-script</s:type>'
+        '<s:parameter>'
+        '<s:name>script</s:name>'
+        '<c:value xsi:type="c:ScriptExpressionEvaluatorType">'
+        # Groovy was the implicit default until Midpoint 4.11 switched to MEL
+        f'<c:language>{GROOVY_LANGUAGE_URI}</c:language>'
+        f'<c:code><![CDATA[\n{groovy}]]></c:code>'
+        '</c:value>'
+        '</s:parameter>'
+        '<s:parameter>'
+        '<s:name>forWholeInput</s:name>'
+        '<c:value>true</c:value>'
+        '</s:parameter>'
+        '</s:action>'
+        '</s:pipeline>'
+        '</s:executeScript>'
+    )

midpoint_cli/client/configuration.py

@@ -0,0 +1,15 @@
+"""Connection settings of a Midpoint client."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class MidpointClientConfiguration:
+    url: str = 'http://localhost:8080/midpoint/'
+    username: str = 'administrator'
+    # No default: a client without a password refuses to call the server (MidpointMissingPassword).
+    password: str = ''
+    # Seconds to keep retrying a request that gets no answer; None reads MIDPOINT_TIMEOUT (default 120).
+    timeout: float | None = None
+    # Seconds to wait for the answer to one REST call; None reads MIDPOINT_READ_TIMEOUT (default 300).
+    read_timeout: float | None = None

midpoint_cli/client/constants.py

@@ -0,0 +1,37 @@
+"""Schema constants shared by the client modules: XML namespaces and status values.
+
+Kept free of imports so every client module, including the dependency-free query builders,
+can use it.
+"""
+
+from typing import Final
+
+# XML namespaces of the Midpoint schemas.
+COMMON_NS: Final = 'http://midpoint.evolveum.com/xml/ns/public/common/common-3'
+AUDIT_NS: Final = 'http://midpoint.evolveum.com/xml/ns/public/common/audit-3'
+API_TYPES_NS: Final = 'http://midpoint.evolveum.com/xml/ns/public/common/api-types-3'
+SCRIPTING_NS: Final = 'http://midpoint.evolveum.com/xml/ns/public/model/scripting-3'
+RESOURCE_INSTANCE_NS: Final = 'http://midpoint.evolveum.com/xml/ns/public/resource/instance-3'
+QUERY_NS: Final = 'http://prism.evolveum.com/xml/ns/public/query-3'
+TYPES_NS: Final = 'http://prism.evolveum.com/xml/ns/public/types-3'
+
+
+class ResultStatus:
+    """Values of OperationResultStatusType: a task's last run result, an operation's outcome."""
+
+    SUCCESS: Final = 'success'
+    WARNING: Final = 'warning'
+    PARTIAL_ERROR: Final = 'partial_error'
+    HANDLED_ERROR: Final = 'handled_error'
+    FATAL_ERROR: Final = 'fatal_error'
+    IN_PROGRESS: Final = 'in_progress'
+
+
+class TaskExecutionState:
+    """Values of TaskExecutionStateType, a task's executionState (Midpoint 4.4+)."""
+
+    RUNNING: Final = 'running'
+    RUNNABLE: Final = 'runnable'
+    WAITING: Final = 'waiting'
+    SUSPENDED: Final = 'suspended'
+    CLOSED: Final = 'closed'

midpoint_cli/client/errors.py

@@ -0,0 +1,74 @@
+"""Exceptions raised by the Midpoint client."""
+
+from midpoint_cli.client.objects import MidpointObjectType, MidpointTask
+
+
+class MidpointServerError(Exception):
+    # HTTP status of the failed REST call, when the server answered one.
+    status_code: int | None = None
+
+
+class MidpointUnsupportedOperation(Exception):
+    pass
+
+
+class MidpointInvalidOid(MidpointServerError):
+    """An OID or path segment was refused before being joined into a REST URL.
+
+    Subclasses MidpointServerError so command handlers report it like any other failed call.
+    """
+
+
+class MidpointObjectNotFound(MidpointServerError):
+    """The server answered 404: the requested object does not exist (or is not visible to the user)."""
+
+
+class MidpointAmbiguousName(MidpointServerError):
+    """A name given instead of an OID matches several objects, so the CLI refuses to pick one.
+
+    Names are only unique per type for some types: task names, for instance, often repeat.
+    Subclasses MidpointServerError so command handlers report it like any other failed lookup.
+    """
+
+    def __init__(self, object_type: MidpointObjectType, name: str, oids: list[str]):
+        self.name = name
+        self.oids = oids
+        super().__init__(
+            f'Ambiguous {object_type.tagname} name {name!r}: {len(oids)} objects have it '
+            f'(OIDs: {", ".join(oids)}). Use an OID instead.'
+        )
+
+
+class MidpointMissingPassword(MidpointServerError):
+    """The client configuration holds no password, so no REST call is sent.
+
+    Subclasses MidpointServerError so command handlers report it like any other failed call.
+    """
+
+
+class MidpointClientNotConfigured(Exception):
+    """Raised when a MidpointClient built without a configuration or REST client tries to talk to a server."""
+
+
+class MidpointAuditScriptRefused(MidpointServerError):
+    """The server refused the Groovy bulk action that audit search relies on (Midpoint 4.11+ defaults)."""
+
+
+class MidpointAuditScriptIncompatible(MidpointServerError):
+    """The audit Groovy script did not compile or link against the server's internal classes."""
+
+
+class TaskExecutionFailure(Exception):
+    """A task run that ended with a result other than success.
+
+    ``task`` is the task as last read from the server, so its statistics (error counts,
+    executed actions) can be shown with the failure; None when it is not known.
+    """
+
+    def __init__(self, message: str, task: MidpointTask | None = None):
+        super().__init__(message)
+        self.message = message
+        self.task = task
+
+    def __repr__(self):
+        return self.message

midpoint_cli/client/logging_config.py

@@ -0,0 +1,122 @@
+"""Class loggers of the system configuration: reading them, and the REST patch that sets one.
+
+The logging configuration lives in SystemConfigurationType/logging. Its shape is the same in
+the 4.4.11 to 4.11.0 schemas (common-core-3.xsd):
+
+* ``logging/rootLoggerLevel``: the level of the root logger;
+* ``logging/classLogger`` (multi-valued container, one value per logger, each with an ``id``):
+  ``level`` (LoggingLevelType), ``appender`` (zero or more names) and ``package``, the logger
+  name (a package or a class).
+
+A level is set with a PATCH carrying an ObjectModificationType, so the rest of the system
+configuration is left alone: a ``replace`` of ``logging/classLogger[<id>]/level`` for an
+existing logger, an ``add`` of a ``logging/classLogger`` value for a new one. Midpoint applies
+a changed logging configuration as soon as the system configuration is saved.
+"""
+
+from dataclasses import dataclass, field
+from xml.etree.ElementTree import Element
+from xml.sax.saxutils import escape as xml_escape
+
+from midpoint_cli.client.constants import API_TYPES_NS, COMMON_NS, TYPES_NS
+from midpoint_cli.client.objects import namespaces
+
+# LoggingLevelType values, the same from 4.4.11 to 4.11.0.
+LOGGING_LEVELS = ('ALL', 'OFF', 'ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE')
+
+
+@dataclass
+class ClassLogger:
+    package: str
+    level: str | None = None
+    appenders: list[str] = field(default_factory=list)
+    # Container value id, which a patch needs to address this logger.
+    container_id: str | None = None
+
+
+@dataclass
+class LoggingConfiguration:
+    root_level: str | None = None
+    class_loggers: list[ClassLogger] = field(default_factory=list)
+
+    def loggers_of(self, package: str) -> list[ClassLogger]:
+        """The class loggers configured for exactly this logger name (normally at most one)."""
+        return [logger for logger in self.class_loggers if logger.package == package]
+
+
+def normalize_level(level: str) -> str:
+    """The LoggingLevelType value for level, ignoring case; ValueError for an unknown level."""
+    normalized = level.strip().upper()
+    if normalized not in LOGGING_LEVELS:
+        raise ValueError(f'Invalid logging level {level!r}, expected one of: {", ".join(LOGGING_LEVELS)}')
+    return normalized
+
+
+def check_logger_name(package: str) -> str:
+    """A logger name as given, refusing an empty one or one containing whitespace."""
+    if not package or any(char.isspace() for char in package):
+        raise ValueError(f'Invalid logger name {package!r}: expected a package or class name such as com.example')
+    return package
+
+
+def _text(parent: Element, path: str) -> str | None:
+    node = parent.find(path, namespaces)
+    text = node.text.strip() if node is not None and node.text is not None else ''
+    return text or None
+
+
+def parse_logging(system_configuration: Element) -> LoggingConfiguration:
+    """The root level and class loggers of a SystemConfigurationType document."""
+    logging = system_configuration.find('c:logging', namespaces)
+    if logging is None:
+        return LoggingConfiguration()
+    loggers = []
+    for node in logging.findall('c:classLogger', namespaces):
+        package = _text(node, 'c:package')
+        if package is None:
+            continue
+        loggers.append(
+            ClassLogger(
+                package=package,
+                level=_text(node, 'c:level'),
+                appenders=[a.text.strip() for a in node.findall('c:appender', namespaces) if a.text and a.text.strip()],
+                container_id=node.attrib.get('id'),
+            )
+        )
+    return LoggingConfiguration(root_level=_text(logging, 'c:rootLoggerLevel'), class_loggers=loggers)
+
+
+_MODIFICATION_START = f"<objectModification xmlns='{API_TYPES_NS}' xmlns:c='{COMMON_NS}' xmlns:t='{TYPES_NS}'>"
+
+
+def class_logger_modification(existing: list[ClassLogger], package: str, level: str) -> str:
+    """The ObjectModificationType setting package to level.
+
+    existing are the class loggers already configured for package: each gets its level
+    replaced, addressed by its container id. With none, a new class logger is added.
+    """
+    if existing:
+        deltas = []
+        for logger in existing:
+            if logger.container_id is None or not logger.container_id.isdigit():
+                raise ValueError(f'The class logger of {package} has no container id, so it cannot be modified')
+            deltas.append(
+                '<itemDelta>'
+                '<t:modificationType>replace</t:modificationType>'
+                f'<t:path>c:logging/c:classLogger[{logger.container_id}]/c:level</t:path>'
+                f'<t:value>{level}</t:value>'
+                '</itemDelta>'
+            )
+        body = ''.join(deltas)
+    else:
+        body = (
+            '<itemDelta>'
+            '<t:modificationType>add</t:modificationType>'
+            '<t:path>c:logging/c:classLogger</t:path>'
+            '<t:value>'
+            f'<c:level>{level}</c:level>'
+            f'<c:package>{xml_escape(package)}</c:package>'
+            '</t:value>'
+            '</itemDelta>'
+        )
+    return _MODIFICATION_START + body + '</objectModification>'