midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/prompt/audit.py

@@ -0,0 +1,253 @@
+"""`audit` command — query Midpoint's audit log to track all server-side changes."""
+
+import re
+import shlex
+from argparse import ArgumentParser, RawTextHelpFormatter
+from typing import cast
+from xml.etree import ElementTree
+from xml.etree.ElementTree import Element
+
+from rich.text import Text
+from rich.tree import Tree
+
+from midpoint_cli.client import (
+    MidpointAuditEvent,
+    MidpointObjectList,
+    MidpointObjectTypes,
+    MidpointServerError,
+    namespaces,
+)
+from midpoint_cli.client.audit_query import AuditQuery, parse_duration
+from midpoint_cli.prompt.base import PromptBase
+from midpoint_cli.prompt.complete import USER, completes
+from midpoint_cli.prompt.console import OUTCOME_STYLE, get_console, is_machine_output, print_rows
+
+# OIDs are UUIDs; anything matching this pattern is treated as a literal OID,
+# everything else is treated as a name to resolve via the users endpoint.
+_OID_RE = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.IGNORECASE)
+
+
+audit_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='audit',
+    description='Query the Midpoint audit log.',
+    epilog="""
+Available commands:
+  ls       List recent audit events (with filters).
+  object   Show change history for a single object.
+  get      Show full details (including deltas) for one event.
+""",
+)
+audit_parser.add_argument('command', help='Audit subcommand to execute.')
+audit_parser.add_argument('arg', help='Subcommand arguments.', nargs='*')
+
+audit_ls_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='audit ls',
+    description='List recent audit events. All filters are ANDed together.',
+)
+audit_ls_parser.add_argument('--since', help='Earliest timestamp, e.g. 1h, 30m, 2d, 1w, or ISO-8601.')
+audit_ls_parser.add_argument('--until', help='Latest timestamp, same syntax as --since.')
+completes(audit_ls_parser.add_argument('--user', help='Initiator OID or name.'), USER)
+audit_ls_parser.add_argument('--type', dest='event_type', help='Audit event type, e.g. modifyObject, addObject.')
+audit_ls_parser.add_argument('--stage', help='Audit event stage, e.g. request, execution.')
+audit_ls_parser.add_argument('--channel', help='Channel filter (substring of channel URI fragment).')
+audit_ls_parser.add_argument('--outcome', help='Outcome filter, e.g. success, fatalError.')
+audit_ls_parser.add_argument('--limit', type=int, default=50, help='Max events to return (0 = no limit).')
+audit_ls_parser.add_argument('--show-deltas', action='store_true', help='Render full deltas under each row.')
+
+audit_object_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='audit object',
+    description='Show audit events targeting a single object.',
+)
+audit_object_parser.add_argument('oid', help='Target object OID.')
+audit_object_parser.add_argument('--limit', type=int, default=50, help='Max events to return (0 = no limit).')
+audit_object_parser.add_argument('--show-deltas', action='store_true', help='Render full deltas under each row.')
+
+audit_get_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='audit get',
+    description='Show full details and deltas for one audit event by event identifier.',
+)
+audit_get_parser.add_argument(
+    'event_identifier', help='Value of the audit eventIdentifier field: the EventIdentifier column of audit ls.'
+)
+
+audit_subparsers: dict[str, ArgumentParser | None] = {
+    'ls': audit_ls_parser,
+    'object': audit_object_parser,
+    'get': audit_get_parser,
+}
+
+
+_EVENT_COLUMN_STYLES = {
+    'Timestamp': 'white',
+    'Stage': 'cyan',
+    'Type': 'bright_cyan',
+    'Initiator': 'blue',
+    'Channel': 'white',
+    'Target': 'blue',
+    'Outcome': 'white',
+    # What `audit get` takes. Last, so the columns before it keep their positions.
+    'EventIdentifier': 'blue',
+}
+
+
+def _event_cell_style(column: str, value: str) -> str | None:
+    if column == 'Outcome':
+        return OUTCOME_STYLE.get(value.replace('-', '_').lower(), 'white')
+    return _EVENT_COLUMN_STYLES.get(column)
+
+
+class AuditClientPrompt(PromptBase):
+    subparsers_audit = audit_subparsers
+
+    def do_audit(self, inp: str) -> None:
+        """Query the Midpoint audit log (subcommands: ls, object, get)."""
+        args = shlex.split(inp)
+        if not args or args[0] in ('-h', '--help'):
+            audit_parser.print_help()
+            return
+        self._dispatch_subcommand(
+            inp,
+            None,
+            audit_subparsers,
+            {'ls': self._audit_ls, 'object': self._audit_object, 'get': self._audit_get},
+            errors=(MidpointServerError, ValueError),
+        )
+
+    @staticmethod
+    def help_audit() -> None:
+        audit_parser.print_help()
+
+    def _audit_ls(self, argv: list[str]) -> None:
+        ns = audit_ls_parser.parse_args(argv)
+        query = AuditQuery(limit=ns.limit)
+        if ns.since:
+            query.since = parse_duration(ns.since)
+        if ns.until:
+            query.until = parse_duration(ns.until)
+        if ns.user:
+            query.initiator_oid = self._resolve_user_oid(ns.user)
+        if ns.event_type:
+            query.event_type = ns.event_type
+        if ns.stage:
+            query.event_stage = ns.stage
+        if ns.channel:
+            query.channel = ns.channel
+        if ns.outcome:
+            query.outcome = ns.outcome
+
+        events = self.client.search_audit(query)
+        # Server returns newest-first so --limit keeps the most recent N;
+        # reverse for display so the most recent ends up at the bottom.
+        events.reverse()
+        self._print_events(events, show_deltas=ns.show_deltas)
+
+    def _audit_object(self, argv: list[str]) -> None:
+        ns = audit_object_parser.parse_args(argv)
+        query = AuditQuery(limit=ns.limit, target_oid=ns.oid)
+        events = self.client.search_audit(query)
+        events.reverse()
+        self._print_events(events, title=f'Audit history for {ns.oid}', show_deltas=ns.show_deltas)
+
+    def _audit_get(self, argv: list[str]) -> None:
+        ns = audit_get_parser.parse_args(argv)
+        query = AuditQuery(limit=0, event_identifier=ns.event_identifier)
+        events = self.client.search_audit(query)
+        if not events:
+            self._fail(f'No audit event found with identifier {ns.event_identifier}')
+            return
+        self._print_events(events, title=f'Audit event {ns.event_identifier}', show_deltas=True)
+
+    def _resolve_user_oid(self, ref: str) -> str:
+        """Resolve a CLI --user value (OID or name) to a user OID."""
+        if _OID_RE.match(ref):
+            return ref
+        match = self.client.find_object(MidpointObjectTypes.USER.value, ref)
+        if match is None:
+            raise ValueError(f'User not found: {ref}')
+        oid = match.get_oid()
+        if oid is None:
+            raise AssertionError
+        return oid
+
+    @classmethod
+    def _print_events(cls, events: MidpointObjectList, title: str = 'Audit events', show_deltas: bool = False) -> None:
+        """Print audit events in the selected output format.
+
+        With deltas, a table is followed by one tree of deltas per event, while the machine
+        formats carry each event's deltas as XML in a Deltas column.
+        """
+        rows = []
+        for event in events:
+            ev = cast(MidpointAuditEvent, event)
+            row = {
+                'Timestamp': ev.get('Timestamp'),
+                'Stage': ev.get('Stage'),
+                'Type': ev.get('EventType'),
+                'Initiator': ev.get('Initiator'),
+                'Channel': ev.get('Channel'),
+                'Target': ev.get('Target'),
+                'Outcome': ev.get('Outcome'),
+                'EventIdentifier': ev.get('EventIdentifier'),
+            }
+            if show_deltas and is_machine_output():
+                row['Deltas'] = '\n'.join(
+                    ElementTree.tostring(delta, encoding='unicode').strip() for delta in ev.get_deltas()
+                )
+            rows.append(row)
+
+        columns = list(_EVENT_COLUMN_STYLES)
+        if show_deltas and is_machine_output():
+            columns.append('Deltas')
+        print_rows(rows, title=title, noun='audit events', columns=columns, cell_style=_event_cell_style)
+        if show_deltas and not is_machine_output():
+            cls._print_event_deltas(events)
+
+    @classmethod
+    def _print_event_deltas(cls, events: MidpointObjectList) -> None:
+        console = get_console()
+        for event in events:
+            ev = cast(MidpointAuditEvent, event)
+            deltas = ev.get_deltas()
+            if not deltas:
+                continue
+            label = ev.get('EventIdentifier') or ev.get('Timestamp') or ''
+            tree = Tree(Text(f'Deltas for {label}', style='bold'))
+            for delta_node in deltas:
+                cls._render_delta(tree, delta_node)
+            console.print(tree)
+
+    @staticmethod
+    def _render_delta(parent: Tree, delta_node: Element) -> None:
+        object_delta = delta_node.find('c:objectDelta', namespaces)
+        if object_delta is None:
+            # Fall back to the delta node itself if structure is different.
+            object_delta = delta_node
+
+        change_type_el = object_delta.find('c:changeType', namespaces)
+        oid_el = object_delta.find('c:oid', namespaces)
+        type_el = object_delta.find('c:objectType', namespaces)
+
+        change_type = change_type_el.text if change_type_el is not None else 'modify'
+        target_oid = oid_el.text if oid_el is not None else ''
+        target_type = type_el.text.split('}')[-1] if type_el is not None and type_el.text else ''
+        header = Text.assemble((change_type or '', 'yellow'), f' {target_type} {target_oid}'.rstrip())
+        delta_branch = parent.add(header)
+
+        for item_delta in object_delta.findall('c:itemDelta', namespaces):
+            mod_type = item_delta.find('c:modificationType', namespaces)
+            path_el = item_delta.find('c:path', namespaces)
+            mod = mod_type.text if mod_type is not None else '?'
+            path_text: str | None
+            path_text = path_el.text if path_el is not None else None
+            label = Text.assemble((mod or '', 'cyan'), ' ', (path_text or '', 'bright_cyan'))
+            item_branch = delta_branch.add(label)
+            for value in item_delta.findall('c:value', namespaces):
+                rendered = ElementTree.tostring(value, encoding='unicode').strip()
+                # Truncate very long values for readability.
+                if len(rendered) > 400:
+                    rendered = rendered[:397] + '...'
+                item_branch.add(Text(rendered))

midpoint_cli/prompt/base.py

@@ -0,0 +1,218 @@
+import contextlib
+import shlex
+from argparse import ArgumentParser, ArgumentTypeError
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from midpoint_cli.client import MidpointAmbiguousName, MidpointServerError, TaskExecutionFailure
+from midpoint_cli.client.objects import MidpointObject, MidpointObjectType, MidpointObjectTypes, MidpointTask
+from midpoint_cli.prompt.console import (
+    create_progress_monitor,
+    create_table,
+    get_console,
+    is_machine_output,
+    print_details,
+    print_error,
+    print_info,
+)
+
+if TYPE_CHECKING:
+    from midpoint_cli.client import MidpointClient
+    from midpoint_cli.prompt.configuration import ResolvedConfiguration
+
+
+def _positive_int(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        raise ArgumentTypeError(f'invalid positive integer: {text!r}') from None
+    if value < 1:
+        raise ArgumentTypeError(f'must be at least 1, got {value}')
+    return value
+
+
+def add_listing_arguments(parser: ArgumentParser, what: str) -> ArgumentParser:
+    """Add the server-side --limit and --filter options shared by the ls subcommands."""
+    parser.add_argument(
+        '--limit',
+        type=_positive_int,
+        metavar='N',
+        help=f'List at most N {what}, sorted by name (paged on the server).',
+    )
+    parser.add_argument(
+        '--filter',
+        metavar='TEXT',
+        help=f'Only list {what} whose name contains TEXT, ignoring case (filtered on the server).',
+    )
+    return parser
+
+
+def add_new_task_arguments(parser: ArgumentParser) -> ArgumentParser:
+    """Add the --no-wait and --no-changes options of the commands that create and start a task."""
+    parser.add_argument(
+        '--no-wait',
+        action='store_true',
+        help='Start the task and print its OID instead of waiting for it to finish.',
+    )
+    parser.add_argument(
+        '--no-changes',
+        action='store_true',
+        help="Don't stream audit events while the task runs (silences the inline change log).",
+    )
+    return parser
+
+
+# A subcommand handler: called with the arguments that follow the subcommand.
+SubcommandHandler = Callable[[list[str]], None]
+
+
+def print_object_detail(obj: Mapping[str, Any], title: str) -> None:
+    """Print one object's properties in the selected output format (role get, org get).
+
+    The table lists the non-empty properties; the machine formats every one, empty ones
+    included, so scripts see the same keys for every object.
+    """
+    if is_machine_output():
+        print_details([obj], as_list=False)
+        return
+    table = create_table(title=title)
+    table.add_column('Attribute', style='cyan')
+    table.add_column('Value', style='white')
+    for attr, value in obj.items():
+        if value is not None and str(value).strip():
+            table.add_row(str(attr), str(value))
+    get_console().print(table)
+
+
+class PromptBase:
+    """Base of the command mixins.
+
+    Besides cmd.Cmd's ``do_<command>``/``help_<command>`` methods, a mixin exposes its parsers
+    as class attributes, which the tab completer reads:
+
+    * ``parser_<command>``: the parser of a command without subcommands;
+    * ``subparsers_<command>``: a mapping of each subcommand to its parser, or to None when it
+      takes no arguments. The command uses the same mapping for dispatch and ``-h``.
+    """
+
+    def __init__(self) -> None:
+        # Note: self.client gets set immediately in MidpointClientPrompt.__init__()
+        # This is just a type declaration - the actual assignment happens in the subclass
+        self.client: MidpointClient
+        # Effective settings and their sources, when started from main(); shown by `info`.
+        self.configuration: ResolvedConfiguration | None = None
+        self.error_code: int | None = None
+        self.error_message: str | None = None
+
+    def _fail(self, message: str | None = None) -> None:
+        """Mark the command as failed (exit code 1); onecmd prints the message, if any, as its error."""
+        self.error_code = 1
+        if message is not None:
+            self.error_message = message
+
+    @staticmethod
+    def _subcommand_help(args: list[str], subparsers: Mapping[str, ArgumentParser | None]) -> bool:
+        """If -h/--help follows a known subcommand, print that subcommand's help and return True."""
+        if args and subparsers.get(args[0]) is not None and any(a in ('-h', '--help') for a in args[1:]):
+            subparser = subparsers[args[0]]
+            if subparser is None:
+                raise AssertionError
+            subparser.print_help()
+            return True
+        return False
+
+    def _dispatch_subcommand(
+        self,
+        inp: str,
+        parser: ArgumentParser | None,
+        subparsers: Mapping[str, ArgumentParser | None],
+        handlers: Mapping[str, SubcommandHandler],
+        *,
+        errors: tuple[type[Exception], ...] = (MidpointServerError,),
+        strict: bool = False,
+    ) -> None:
+        """Run the handler of the subcommand that inp starts with, on the arguments after it.
+
+        -h after a known subcommand prints that subcommand's help. parser, a command parser
+        with ``command`` and ``arg`` positionals, prints the command's help for -h and reports
+        a missing subcommand as a usage error; without one, the first word is the subcommand.
+        An unknown subcommand fails with ``Unknown command <name>``; with strict, arguments
+        after it are a usage error instead. An exception of one of errors raised by the
+        handler fails the command with its message.
+        """
+        try:
+            args = shlex.split(inp)
+            if self._subcommand_help(args, subparsers):
+                return
+            if parser is None:
+                command, extra = (args[0], args[1:]) if args else ('', [])
+            else:
+                # Each subcommand parses its own options: they pass through here.
+                ns, unknown = parser.parse_known_args(args)
+                command, extra = ns.command, ns.arg + unknown
+            handler = handlers.get(command)
+            if handler is None:
+                if strict and extra and parser is not None:
+                    parser.error(f'unrecognized arguments: {" ".join(extra)}')
+                self._fail(f'Unknown command {command}')
+                return
+            handler(args[1:])
+        except errors as e:
+            self._fail(str(e))
+
+    def _list_shortcut(self, inp: str, shortcut: str, command: str, run: Callable[[str], object]) -> None:
+        """A no-argument shortcut for `<command> ls` (users, roles, ...): run('ls'), or fail on arguments."""
+        if inp.strip():
+            self._fail(f'"{shortcut}" takes no arguments. Did you mean "{command} {inp.strip()}"?')
+            return
+        run('ls')
+
+    def _find_reference(self, object_type: MidpointObjectType, reference: str, label: str) -> MidpointObject | None:
+        """The object a CLI reference (OID or name) designates, or None after printing why there is none.
+
+        Used by commands that loop over several references, so one bad reference (not found, or a
+        name shared by several objects) is reported without stopping the others; the command
+        still fails (exit code 1).
+        """
+        try:
+            found = self.client.find_object(object_type, reference)
+        except MidpointAmbiguousName as e:
+            self._fail()
+            print_error(str(e))
+            return None
+        if found is None:
+            self._fail()
+            print_error(f'{label} reference not found: {reference}')
+        return found
+
+    def _require_object(self, object_type: MidpointObjectType, reference: str, label: str) -> MidpointObject | None:
+        """The object a CLI reference (OID or name) designates, or None after failing with `<label> not found`.
+
+        A name shared by several objects raises MidpointAmbiguousName, a MidpointServerError.
+        """
+        found = self.client.find_object(object_type, reference)
+        if found is None:
+            self._fail(f'{label} not found: {reference}')
+        return found
+
+    def _follow_new_task(self, task_oid: str, task_name: str, no_wait: bool, show_changes: bool) -> None:
+        """Report a task the command created, then follow it to completion like `task run`.
+
+        With no_wait, the task OID is printed on standard output, so a script can capture it.
+        """
+        print_info(f"Task '{task_name}' started: {task_oid}")
+        if no_wait:
+            print(task_oid)
+            return
+        try:
+            task = self.client.run_new_task(task_oid, create_progress_monitor(), show_changes=show_changes)
+            get_console().print(task.get_full_description())
+        except TaskExecutionFailure as e:
+            # The task as last read while waiting, with its statistics; fetched when not known.
+            failed: MidpointObject | None = e.task
+            if failed is None:
+                with contextlib.suppress(MidpointServerError):  # The failure itself is reported below.
+                    failed = self.client.get_object(MidpointObjectTypes.TASK.value, task_oid)
+            if isinstance(failed, MidpointTask):
+                get_console().print(failed.get_full_description())
+            self._fail(e.message)