qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/formatters.py

@@ -0,0 +1,896 @@
+"""
+Output formatting for qualys-cli.
+
+Default (interactive): rich table, first --limit rows + count footer.
+Default (non-interactive / piped): JSON — auto-detected via stdout TTY check.
+
+Format flags:
+  --format json     full JSON to stdout, no decoration
+  --format jsonl    one flattened JSON object per line (NDJSON)
+  --format yaml     full YAML
+  --format table    rich table (forced even when piped)
+  --format csv      RFC-4180 CSV with header row
+  --format tsv      tab-separated values with header
+  --format markdown GitHub-flavoured Markdown table
+
+Composable post-processing flags (work with any format, on every command —
+injected by cli.main() as click options with expose_value=False, so command
+signatures don't need to thread them):
+  --where <predicate>         Filter rows. Supported predicates:
+                                field=value        case-insensitive equality
+                                field!=value       inequality
+                                field~regex        case-insensitive substring
+                                field>=N | >N      numeric / lexicographic
+                                field<=N | <N
+                              Field names match row keys case-insensitively
+                              (so ``severity`` matches Qualys ``SEVERITY``).
+  --columns name,id,status    Override the default table columns
+  --sort field[:asc|:desc]    Sort rows in memory before rendering
+  --jq '.path.to.thing'       jq-lite expression evaluated on the parsed data
+  --limit 0                   Remove the default 25-row cap
+
+The jq expression accepts:
+  ``.foo``, ``.foo.bar``  — dotted key access
+  ``.foo[]``              — flatten a list of dicts
+  ``.foo[3]``             — list index
+  No expression chaining beyond a single ``[]`` segment is supported by design;
+  for anything more complex, pipe through ``jq``.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import re
+import sys
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table as _Table
+from rich.text import Text
+
+_console = Console()
+_err = Console(stderr=True)
+
+DEFAULT_LIMIT = 25
+
+
+def apply_output_mode(mode: str) -> None:
+    global _console, _err
+    if mode == "agentic":
+        _console = Console(force_terminal=False, no_color=True)
+        _err = Console(stderr=True, force_terminal=False, no_color=True)
+    else:
+        _console = Console(force_terminal=True)
+        _err = Console(stderr=True, force_terminal=True)
+
+
+_STATUS_MAP: dict[str, str] = {
+    "active": "green", "running": "bright_green", "success": "green",
+    "complete": "green", "completed": "green", "enabled": "green",
+    "finished": "green", "passed": "green", "valid": "green",
+    "error": "red", "failed": "red", "inactive": "red",
+    "disabled": "red", "canceled": "red", "cancelled": "red",
+    "deleted": "red", "invalid": "red",
+    "pending": "yellow", "queued": "yellow", "processing": "yellow",
+    "warning": "yellow", "submitted": "yellow", "scheduled": "yellow",
+    "paused": "yellow", "timeout": "yellow",
+    "new": "cyan", "draft": "cyan", "open": "cyan", "unknown": "dim",
+}
+
+_STATUS_COLS = {"status", "state", "phase", "result", "condition"}
+
+
+# ---------------------------------------------------------------------------
+# Module-level switches set by the CLI on startup
+# ---------------------------------------------------------------------------
+
+REDACT_FIELDS: list[str] = []
+"""Per-profile output redaction list. Walks every dict in the rendered payload
+and replaces matching field values with ``***REDACTED***``."""
+
+LOCKED_MODE: bool = False
+"""Set by the CLI root callback when the active profile has ``locked_mode =
+true``. Disables free-form ``--output-file`` writes so a scope-restricted
+profile can't be used to exfiltrate data to an arbitrary filesystem path."""
+
+
+# Global post-processing flags (--where / --columns / --sort / --jq) are
+# injected into every Typer command as click Options with expose_value=False.
+# Their callbacks stash values here so output() can pick them up without
+# requiring every command signature to thread the kwargs explicitly.
+_POST_OPTS: ContextVar[dict[str, Any] | None] = ContextVar("post_opts", default=None)
+
+
+def set_post_process_opt(name: str, value: Any) -> None:
+    if value is None:
+        return
+    current = dict(_POST_OPTS.get() or {})
+    current[name] = value
+    _POST_OPTS.set(current)
+
+
+def _post_opt(name: str) -> Any:
+    opts = _POST_OPTS.get()
+    return opts.get(name) if opts else None
+
+
+def reset_post_process_opts() -> None:
+    """Used by tests to reset the per-invocation context."""
+    _POST_OPTS.set(None)
+
+
+def _redact_payload(data: Any) -> Any:
+    if not REDACT_FIELDS:
+        return data
+    keys = {k.strip().lower() for k in REDACT_FIELDS if k.strip()}
+    if not keys:
+        return data
+    return _walk_redact(data, keys)
+
+
+def _record_to_history(data: Any) -> None:
+    """Persist *data* against the active correlation ID so ``last`` / ``replay``
+    can re-render it later. Best-effort: any error is swallowed since the
+    user's command has already completed successfully by the time we get here.
+    """
+    try:
+        from . import audit as _audit
+        from . import history as _history
+        if not _audit.CORRELATION_ID or not _audit.PROFILE_NAME:
+            return
+        _history.record(
+            _audit.PROFILE_NAME,
+            _audit.CORRELATION_ID,
+            list(sys.argv),
+            data,
+        )
+    except Exception:
+        pass
+
+
+def _walk_redact(obj: Any, keys: set[str]) -> Any:
+    if isinstance(obj, dict):
+        return {
+            k: ("***REDACTED***" if isinstance(k, str) and k.lower() in keys
+                else _walk_redact(v, keys))
+            for k, v in obj.items()
+        }
+    if isinstance(obj, list):
+        return [_walk_redact(x, keys) for x in obj]
+    return obj
+
+
+# ---------------------------------------------------------------------------
+# jq-lite query
+# ---------------------------------------------------------------------------
+
+_QUERY_SEGMENT_RE = re.compile(r"^([A-Za-z0-9_-]+)(\[\d*\])?$")
+
+
+def apply_query(data: Any, expr: str) -> Any:
+    """Evaluate a *very* limited jq-style expression against *data*.
+
+    Supported tokens (separated by ``.``):
+      - ``foo``        — dict key
+      - ``foo[]``      — dict key, then iterate the list
+      - ``foo[3]``     — dict key, then index 3
+
+    Wildcards (``*``), pipes, and any other jq syntax are **not** supported.
+    Earlier builds accepted ``*`` in the segment regex but treated it as a
+    literal dict key, silently returning ``None``. The regex now rejects
+    such input outright; callers who need richer expressions should pipe
+    through real ``jq``.
+    """
+    if not expr:
+        return data
+    cur: Any = data
+    body = expr.lstrip(".")
+    if not body:
+        return data
+    for raw in body.split("."):
+        if not raw:
+            continue
+        m = _QUERY_SEGMENT_RE.match(raw)
+        if not m:
+            return None
+        key, idx = m.group(1), m.group(2)
+        if isinstance(cur, dict):
+            cur = cur.get(key)
+        elif isinstance(cur, list):
+            cur = [x.get(key) if isinstance(x, dict) else None for x in cur]
+        else:
+            return None
+        if idx is not None:
+            inner = idx[1:-1]
+            if inner == "":
+                # `[]` flattens one level
+                if isinstance(cur, list):
+                    flat: list[Any] = []
+                    for x in cur:
+                        if isinstance(x, list):
+                            flat.extend(x)
+                        else:
+                            flat.append(x)
+                    cur = flat
+            else:
+                try:
+                    n = int(inner)
+                except ValueError:
+                    return None
+                if isinstance(cur, list) and -len(cur) <= n < len(cur):
+                    cur = cur[n]
+                else:
+                    return None
+    return cur
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def output(
+    data: Any,
+    *,
+    format: str = "table",
+    limit: int | None = DEFAULT_LIMIT,
+    output_file: str | None = None,
+    raw: bool = False,
+    fields: list[str] | None = None,
+    where: str | None = None,
+    columns: str | None = None,
+    sort: str | None = None,
+    query: str | None = None,
+) -> None:
+    """Render API response data according to user-selected format.
+
+    Composable post-processing happens in this order:
+        1. ``--query`` reshapes the payload (jq-lite path).
+        2. PII / customer-field redaction via the profile's ``redact_fields``.
+        3. ``--where`` filters rows after extraction.
+        4. ``--sort`` sorts rows.
+        5. ``--columns`` overrides the default table column set.
+
+    The fully-processed payload is also persisted to the per-profile history
+    cache (``~/.config/qualys-cli/history/<profile>/<correlation>.json``) so
+    ``qualys-cli last`` and ``qualys-cli replay <id>`` can re-render it
+    without hitting the API again.
+    """
+    # Pull post-processing flags from the per-invocation contextvar when
+    # caller didn't pass them explicitly. The CLI's main() injects --where,
+    # --columns, --sort, --jq on every command so users don't need each
+    # command signature to thread them.
+    if where is None:
+        where = _post_opt("where")
+    if columns is None:
+        columns = _post_opt("columns")
+    if sort is None:
+        sort = _post_opt("sort")
+        if sort is None:
+            sort_by = _post_opt("sort_by")
+            if sort_by:
+                sort = f"{sort_by}:{'desc' if _post_opt('sort_desc') else 'asc'}"
+    if query is None:
+        query = _post_opt("jq")
+
+    if query:
+        data = apply_query(data, query)
+
+    data = _redact_payload(data)
+    _record_to_history(data)
+
+    # Export formats default to "all rows" — the 25-row table cap is for
+    # interactive previewing. CSV / TSV / Markdown are typically piped to
+    # spreadsheets or tickets; truncating silently is a footgun. A user who
+    # *did* explicitly pass --limit gets their value through unchanged
+    # (DEFAULT_LIMIT means "no override given"; any other value is honoured).
+    if format in ("csv", "tsv", "markdown") and limit == DEFAULT_LIMIT:
+        limit = 0
+
+    if raw:
+        print(json.dumps(data, default=str) if not isinstance(data, str) else data)
+        return
+
+    # Auto-switch table → json on non-TTY
+    if format == "table" and not _console.is_terminal:
+        format = "json"
+
+    if output_file:
+        guard_output_file()
+        _dump_file(data, output_file)
+        if _err.is_terminal:
+            _err.print(f"[dim]Full data written to[/dim] [bold]{output_file}[/bold]")
+
+    # Resolve the user's column override into the fields list
+    cols_override = (
+        [c.strip() for c in columns.split(",") if c.strip()] if columns else None
+    )
+    fields = fields or cols_override
+
+    if format == "json":
+        print(json.dumps(data, indent=2, default=str))
+    elif format == "jsonl":
+        _render_jsonl(data, where=where, sort=sort)
+    elif format == "yaml":
+        _console.print(yaml.dump(data, default_flow_style=False, allow_unicode=True))
+    elif format in ("csv", "tsv"):
+        _render_dsv(data, sep="\t" if format == "tsv" else ",",
+                    where=where, sort=sort, fields=fields)
+    elif format == "markdown":
+        _render_markdown(data, where=where, sort=sort, fields=fields, limit=limit)
+    else:
+        _render_table(data, limit=limit, fields=fields, where=where, sort=sort)
+
+
+def guard_output_file() -> None:
+    """Raise a clean CLI error if the active profile is locked and the
+    caller is about to write to a free-form ``--output-file`` path.
+
+    Used by commands that stream raw response bytes directly to disk
+    (bypassing :func:`output`'s own ``--output-file`` handling), e.g.
+    ``sub export`` and ``sub user-prefs export``.
+    """
+    if not LOCKED_MODE:
+        return
+    import typer
+    output_error(
+        "This profile is in locked mode — free-form --output-file writes "
+        "are disabled. Redirect stdout instead.",
+        title="Locked mode",
+    )
+    raise typer.Exit(3)
+
+
+def output_error(message: str, title: str = "Error") -> None:
+    if not _err.is_terminal:
+        print(json.dumps({"error": message, "type": title.lower().replace(" ", "_")}),
+              file=sys.stderr)
+        return
+    _err.print(
+        Panel(
+            f"[white]{message}[/white]",
+            title=f"[bold red] {title} [/bold red]",
+            border_style="red",
+            padding=(0, 1),
+            expand=False,
+        )
+    )
+
+
+def output_success(message: str) -> None:
+    if _err.is_terminal:
+        _err.print(f"  [bold green]✓[/bold green]  {message}")
+
+
+def output_warn(message: str) -> None:
+    if not _err.is_terminal:
+        print(json.dumps({"warning": message}), file=sys.stderr)
+        return
+    _err.print(f"  [bold yellow]⚠[/bold yellow]  [yellow]{message}[/yellow]")
+
+
+def output_info(message: str) -> None:
+    if _err.is_terminal:
+        _err.print(f"  [bold cyan]ℹ[/bold cyan]  [dim]{message}[/dim]")
+
+
+@contextmanager
+def spinner(label: str = "Fetching…") -> Generator[None, None, None]:
+    if _err.is_terminal:
+        with _err.status(f"[dim]{label}[/dim]", spinner="dots"):
+            yield
+    else:
+        yield
+
+
+# ---------------------------------------------------------------------------
+# Filter / sort
+# ---------------------------------------------------------------------------
+
+_WHERE_OP_RE = re.compile(r"\s*(>=|<=|!=|>|<|=|~)\s*")
+
+
+def _row_get_ci(row: dict[str, Any], field: str) -> Any:
+    """Lookup *field* in *row* with an exact match first, then case-insensitive
+    fallback so users can write ``severity`` and match a column named
+    ``SEVERITY`` (common in Qualys VM/PC XML responses)."""
+    if field in row:
+        return row[field]
+    lf = field.lower()
+    for k, v in row.items():
+        if isinstance(k, str) and k.lower() == lf:
+            return v
+    return None
+
+
+_CMP_OPS = {
+    ">":  lambda a, b: a > b,
+    ">=": lambda a, b: a >= b,
+    "<":  lambda a, b: a < b,
+    "<=": lambda a, b: a <= b,
+}
+
+
+def _compare(left: Any, right: str, op: str) -> bool:
+    lstr = "" if left is None else str(left)
+    if op == "=":
+        return lstr.lower() == right.lower()
+    if op == "!=":
+        return lstr.lower() != right.lower()
+    cmp = _CMP_OPS.get(op)
+    if cmp is None:
+        return False
+    try:
+        return bool(cmp(float(left), float(right)))
+    except (TypeError, ValueError):
+        return bool(cmp(lstr, right))
+
+
+def _apply_where(rows: list[dict[str, Any]], where: str | None) -> list[dict[str, Any]]:
+    """Filter *rows* by a single predicate.
+
+    Supports:
+      ``field = value``    (case-insensitive string equality)
+      ``field != value``
+      ``field ~ regex``    (case-insensitive substring match)
+      ``field >= value``   (numeric when both sides parse as numbers,
+                            else lexicographic)
+      ``field > value``    (and the obvious ``<``, ``<=`` variants)
+
+    Field names are matched case-insensitively against row keys so callers
+    can write ``severity`` for Qualys XML columns like ``SEVERITY``.
+    """
+    if not where:
+        return rows
+    expr = where.strip()
+    m = _WHERE_OP_RE.search(expr)
+    if not m or m.start() == 0:
+        return rows
+    field = expr[:m.start()].strip()
+    op = m.group(1)
+    value = expr[m.end():].strip()
+    if op == "~":
+        try:
+            rx = re.compile(value, re.IGNORECASE)
+        except re.error:
+            return rows
+        return [r for r in rows if rx.search(str(_row_get_ci(r, field) or ""))]
+    return [r for r in rows if _compare(_row_get_ci(r, field), value, op)]
+
+
+def _apply_sort(rows: list[dict[str, Any]], sort: str | None) -> list[dict[str, Any]]:
+    if not sort:
+        return rows
+    spec = sort.strip()
+    desc = False
+    if ":" in spec:
+        spec, _, direction = spec.partition(":")
+        desc = direction.strip().lower().startswith("desc")
+    field = spec.strip()
+
+    def key(r: dict[str, Any]) -> tuple[int, Any]:
+        v = _row_get_ci(r, field)
+        if v is None or v == "":
+            return (1, "")
+        try:
+            return (0, float(v))
+        except (TypeError, ValueError):
+            return (0, str(v).lower())
+
+    return sorted(rows, key=key, reverse=desc)
+
+
+# ---------------------------------------------------------------------------
+# Renderers
+# ---------------------------------------------------------------------------
+
+def _render_table(
+    data: Any, limit: int | None, fields: list[str] | None,
+    where: str | None = None, sort: str | None = None,
+) -> None:
+    rows, total = _extract_rows(data)
+    rows = _apply_where(rows, where)
+    rows = _apply_sort(rows, sort)
+
+    if not rows:
+        if _err.is_terminal:
+            _err.print("  [dim]No results.[/dim]")
+        return
+
+    no_cap = limit is None or limit == 0
+    display = rows if no_cap else rows[:limit]
+    cols = fields or _infer_columns(display)
+
+    table = _Table(
+        box=box.SIMPLE_HEAD,
+        header_style="bold",
+        border_style="dim",
+        show_edge=False,
+        padding=(0, 1),
+        row_styles=["", "dim"],
+    )
+    for col in cols:
+        table.add_column(col, overflow="fold", max_width=64, no_wrap=False)
+
+    for row in display:
+        table.add_row(*[_colorize(c, str(_get(row, c))) for c in cols])
+
+    _console.print()
+    _console.print(table)
+
+    if _err.is_terminal:
+        shown = len(display)
+        if total is not None and total > shown:
+            _err.print(
+                f"  [dim]Showing {shown:,} of {total:,}"
+                "  ·  use [bold]--output-file[/bold] to export all[/dim]"
+            )
+        elif not no_cap and len(rows) > shown:
+            _err.print(
+                f"  [dim]Showing {shown:,} of {len(rows):,}"
+                "  ·  use [bold]--limit 0[/bold] or"
+                " [bold]--output-file[/bold] to see all[/dim]"
+            )
+        _console.print()
+
+
+def _render_jsonl(data: Any, where: str | None = None, sort: str | None = None) -> None:
+    """Emit one flattened JSON object per line (NDJSON).
+
+    Streaming-friendly: we flush after each row so consumers (jq, awk,
+    Splunk's json sourcetype, …) can start working before the whole list
+    has been written.
+    """
+    rows, _ = _extract_rows(data)
+    rows = _apply_where(rows, where)
+    rows = _apply_sort(rows, sort)
+    out = sys.stdout
+    for row in rows:
+        out.write(json.dumps(row, default=str))
+        out.write("\n")
+        out.flush()
+
+
+def _render_dsv(
+    data: Any, *, sep: str,
+    where: str | None, sort: str | None, fields: list[str] | None,
+) -> None:
+    rows, _ = _extract_rows(data)
+    rows = _apply_where(rows, where)
+    rows = _apply_sort(rows, sort)
+    if not rows:
+        return
+    cols = fields or _infer_columns(rows)
+    buf = io.StringIO()
+    w = csv.writer(buf, delimiter=sep, quoting=csv.QUOTE_MINIMAL, lineterminator="\n")
+    w.writerow(cols)
+    for r in rows:
+        w.writerow([str(r.get(c, "")) for c in cols])
+    sys.stdout.write(buf.getvalue())
+    sys.stdout.flush()
+
+
+def _render_markdown(
+    data: Any, *, where: str | None, sort: str | None,
+    fields: list[str] | None, limit: int | None,
+) -> None:
+    rows, _ = _extract_rows(data)
+    rows = _apply_where(rows, where)
+    rows = _apply_sort(rows, sort)
+    if not rows:
+        return
+    no_cap = limit is None or limit == 0
+    display = rows if no_cap else rows[:limit]
+    cols = fields or _infer_columns(display)
+    out = sys.stdout
+
+    def cell(v: Any) -> str:
+        s = str(v).replace("|", "\\|").replace("\n", " ")
+        return s
+
+    out.write("| " + " | ".join(cols) + " |\n")
+    out.write("|" + "|".join("---" for _ in cols) + "|\n")
+    for r in display:
+        out.write("| " + " | ".join(cell(r.get(c, "")) for c in cols) + " |\n")
+    out.flush()
+
+
+def _colorize(col: str, val: str) -> Text:
+    text = Text(val)
+    if any(kw in col.lower() for kw in _STATUS_COLS):
+        color = _STATUS_MAP.get(val.lower().strip())
+        if color:
+            text.stylize(f"bold {color}" if color != "dim" else color)
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Streaming JSONL helper (for `qualys-cli batch` and bulk pipelines)
+# ---------------------------------------------------------------------------
+
+def stream_jsonl(rows: Iterable[dict[str, Any]]) -> None:
+    """Stream an iterator of dicts as NDJSON to stdout."""
+    out = sys.stdout
+    for row in rows:
+        out.write(json.dumps(row, default=str))
+        out.write("\n")
+        out.flush()
+
+
+# ---------------------------------------------------------------------------
+# Data extraction
+# ---------------------------------------------------------------------------
+
+def _parse_int(v: Any) -> int | None:
+    if v is None:
+        return None
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _extract_rows(data: Any) -> tuple[list[dict[str, Any]], int | None]:
+    if isinstance(data, list):
+        return [_flatten(r) for r in data], None
+
+    if not isinstance(data, dict):
+        return [], None
+
+    for list_key in ("data", "items", "content", "list", "results"):
+        if isinstance(data.get(list_key), list):
+            total = _parse_int(
+                data.get("total") or data.get("totalCount") or data.get("count")
+            )
+            return [_flatten(r) for r in data[list_key]], total
+
+    _SR_META = frozenset({
+        "responseCode", "count", "hasMoreRecords", "lastId",
+        "@xmlns:xsi", "@xsi:noNamespaceSchemaLocation",
+    })
+    sr = data.get("ServiceResponse")
+    if isinstance(sr, dict):
+        total = _parse_int(sr.get("count"))
+        sr_data = sr.get("data")
+        if isinstance(sr_data, dict):
+            for v in sr_data.values():
+                if isinstance(v, list):
+                    return [_flatten(r) for r in v], total
+                if isinstance(v, dict):
+                    return [_flatten(v)], total
+        elif isinstance(sr_data, list):
+            return [_flatten(r) for r in sr_data], total
+        for k, v in sr.items():
+            if k in _SR_META or k == "data":
+                continue
+            if isinstance(v, list):
+                return [_flatten(r) for r in v], total
+            if isinstance(v, dict):
+                for v2 in v.values():
+                    if isinstance(v2, list):
+                        return [_flatten(r) for r in v2], total
+                return [_flatten(v)], total
+        # Fall-through: SR has no rows container and no non-meta fields. This
+        # is the shape of the */count/* endpoints (e.g. `ca agent count` or
+        # `was webapp count`), whose entire payload is metadata. Surface the
+        # `count` as a synthetic single-row so the table renderer shows the
+        # value instead of an empty grid. Without this, `output()` returns
+        # `[{}]` — truthy enough to skip the "No results" branch but with no
+        # columns to render, leaving the user with a blank screen after the
+        # spinner clears.
+        remaining = {k: v for k, v in sr.items() if k not in _SR_META and k != "data"}
+        if not remaining and total is not None:
+            return [{"count": total}], total
+        return [_flatten(remaining)], None
+
+    peeled = _peel_vm_xml_envelope(data)
+    if peeled is not None:
+        return peeled
+
+    found = _find_list_key(data)
+    if found is not None:
+        return [_flatten(r) for r in found], None
+
+    deep = _find_dict_list(data)
+    if deep is not None:
+        total = _parse_int(
+            data.get("count") or data.get("total") or data.get("totalCount")
+        )
+        return [_flatten(r) for r in deep], total
+
+    return [_flatten(data)], None
+
+
+# Metadata fields on a Qualys <RESPONSE> body that never carry row data and
+# should be skipped when locating the rows container.
+_VM_RESPONSE_META = frozenset({"DATETIME", "STATUS", "COUNT", "USER_LOGIN"})
+
+
+def _peel_vm_xml_envelope(
+    data: dict[str, Any],
+) -> tuple[list[dict[str, Any]], int | None] | None:
+    """Extract rows from a Qualys VM/PC XML envelope.
+
+    Shape: ``{<X>_OUTPUT: {RESPONSE: {DATETIME, STATUS, COUNT, <rows>}}}``
+    (or a bare top-level ``{RESPONSE: {...}}``).
+
+    The rows container is not always ``*_LIST`` — many endpoints wrap rows
+    under a plural noun (e.g. ``AUTH_VAULTS > AUTH_VAULT``). xmltodict also
+    collapses an empty list into ``None``, which previously fell through to
+    the catch-all and rendered the entire envelope as one stringified cell.
+    Returns ``None`` when *data* is not a recognisable envelope.
+    """
+    response: dict[str, Any] | None = None
+    if len(data) == 1:
+        only_key = next(iter(data))
+        only_val = data[only_key]
+        if isinstance(only_val, dict):
+            inner = only_val.get("RESPONSE")
+            if isinstance(inner, dict) and (
+                only_key.endswith("_OUTPUT") or only_key == "SIMPLE_RETURN"
+                or only_key == "BATCH_RETURN"
+            ):
+                response = inner
+    if response is None and isinstance(data.get("RESPONSE"), dict) and len(data) == 1:
+        response = data["RESPONSE"]
+    if response is None:
+        return None
+
+    count = _parse_int(response.get("COUNT"))
+
+    for k, v in response.items():
+        if k in _VM_RESPONSE_META:
+            continue
+        if isinstance(v, list):
+            return [_flatten(r) for r in v], count
+        if isinstance(v, dict):
+            for inner_v in v.values():
+                if isinstance(inner_v, list):
+                    return [_flatten(r) for r in inner_v], count
+                if isinstance(inner_v, dict):
+                    return [_flatten(inner_v)], count
+            # Empty wrapper dict — treat as no rows.
+
+    # No rows container located. Either an empty list (COUNT=0 / all-None
+    # children) or an action confirmation like SIMPLE_RETURN with just
+    # CODE/TEXT — surface those as a single flat row, omitting the
+    # DATETIME/STATUS/COUNT/USER_LOGIN metadata so the table doesn't get
+    # cluttered with envelope bookkeeping.
+    non_meta = {k: v for k, v in response.items() if k not in _VM_RESPONSE_META}
+    if count == 0 or not non_meta or all(v is None for v in non_meta.values()):
+        return [], count if count is not None else 0
+    return [_flatten(non_meta)], count
+
+
+def _find_dict_list(data: dict[str, Any], depth: int = 0) -> list[Any] | None:
+    if depth > 4:
+        return None
+    for v in data.values():
+        if isinstance(v, list) and v and isinstance(v[0], dict):
+            return v
+        if isinstance(v, dict):
+            found = _find_dict_list(v, depth + 1)
+            if found is not None:
+                return found
+    return None
+
+
+def _find_list_key(data: dict[str, Any], depth: int = 0) -> list[Any] | None:
+    if depth > 5:
+        return None
+    for k, v in data.items():
+        if k.endswith("_LIST"):
+            if isinstance(v, list):
+                return v
+            if isinstance(v, dict):
+                for child_v in v.values():
+                    if isinstance(child_v, list):
+                        return child_v
+                    if isinstance(child_v, dict):
+                        return [child_v]
+                return [v]
+            # xmltodict collapses ``<X_LIST/>`` to None — that's an empty
+            # list, not "no _LIST wrapper found". Returning [] here prevents
+            # the catch-all from stringifying the surrounding envelope.
+            if v is None:
+                return []
+        if isinstance(v, dict):
+            result = _find_list_key(v, depth + 1)
+            if result is not None:
+                return result
+    return None
+
+
+def _flatten(obj: Any, prefix: str = "", depth: int = 0) -> dict[str, str]:
+    if not isinstance(obj, dict):
+        return {"value": str(obj)}
+    result: dict[str, str] = {}
+    for k, v in obj.items():
+        key = f"{prefix}{k}" if prefix else k
+        if isinstance(v, dict) and depth < 1:
+            result.update(_flatten(v, prefix=f"{key}.", depth=depth + 1))
+        elif isinstance(v, list):
+            if v and isinstance(v[0], dict):
+                result[key] = f"[{len(v)} item{'s' if len(v) != 1 else ''}]"
+            else:
+                result[key] = ", ".join(str(i) for i in v[:5])
+        else:
+            result[key] = str(v) if v is not None else ""
+    return result
+
+
+def _infer_columns(rows: list[dict[str, Any]]) -> list[str]:
+    if not rows:
+        return []
+    sample = rows[0]
+    all_keys = list(sample.keys())
+    priority = [
+        "id", "ID", "name", "NAME", "title", "TITLE", "ref", "REF",
+        "status", "STATUS", "type", "TYPE", "ip", "IP",
+        "action", "ACTION", "datetime", "DATETIME",
+    ]
+
+    def looks_complex(key: str) -> bool:
+        for r in rows[:5]:
+            v = r.get(key)
+            if v is None or v == "":
+                continue
+            s = str(v).strip()
+            if s.startswith(("{", "[")) or s.startswith("[0 item") or s.endswith("items]"):
+                return True
+        return False
+
+    cols: list[str] = []
+    for p in priority:
+        if p in all_keys and p not in cols:
+            cols.append(p)
+    for k in all_keys:
+        if k not in cols and not looks_complex(k):
+            cols.append(k)
+    for k in all_keys:
+        if k not in cols:
+            cols.append(k)
+    return cols[:8]
+
+
+def _get(row: dict[str, Any], col: str) -> Any:
+    return row.get(col, "")
+
+
+# ---------------------------------------------------------------------------
+# File dump
+# ---------------------------------------------------------------------------
+
+def _dump_file(data: Any, path: str) -> None:
+    p = Path(path)
+    suffix = p.suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        p.write_text(yaml.dump(data, default_flow_style=False, allow_unicode=True))
+    elif suffix == ".csv":
+        rows, _ = _extract_rows(data)
+        if rows:
+            cols = _infer_columns(rows)
+            buf = io.StringIO()
+            w = csv.writer(buf, lineterminator="\n")
+            w.writerow(cols)
+            for r in rows:
+                w.writerow([str(r.get(c, "")) for c in cols])
+            p.write_text(buf.getvalue())
+        else:
+            p.write_text("")
+    elif suffix in (".jsonl", ".ndjson"):
+        rows, _ = _extract_rows(data)
+        with p.open("w") as fh:
+            for r in rows:
+                fh.write(json.dumps(r, default=str))
+                fh.write("\n")
+    else:
+        p.write_text(json.dumps(data, indent=2, default=str))