xsoar-cli 2.3.0__tar.gz → 2.4.0__tar.gz

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/CHANGELOG.md

@@ -8,6 +8,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- `content get-detached --type all` queries both scripts and playbooks and displays results for each type.
+- `content list --output-format` option (choices: `table`, `json`, `plain`, default: `table`). `table` is human-readable aligned columns, `json` is machine-readable, and `plain` is tab-separated values suitable for piping to tools like `grep`.
+- `content list --search TERM` option. Filters the listed items with a case-insensitive substring match against each item's id, name, and description. Content types and integration brands with no matching items are omitted, and a `No content matching '<term>' found.` message is shown when nothing matches.
+- `content describe --type [script|playbook|command] NAME` command. Shows a single content item in detail: description, arguments, and inputs/outputs. Commands also show the integration brand and its configured instances (name and state). Supports `--output-format [table|json]` (default: `table`). See the [content README](src/xsoar_cli/commands/content/README.md) for details.
+
+### Changed
+
+- `content get-detached` now prints a human-readable summary instead of raw JSON. Output is a count followed by one line per item in the form `<name> (ID: <id>)`, or `No detached <type> found` when there are none.
+- **Breaking:** `content list` now defaults to a human-readable table instead of JSON. Use `--output-format json` for machine-readable output.
+- `content list` playbook output now shows the playbook ID and description (read from the `comment` field) instead of the name and ID.
+- `content list` command output now shows the command name and description and no longer includes the integration brand. The summary-level JSON structure for commands is now a list of `{name, description}` objects instead of plain command-name strings.
+
+### Removed
+
+- **Breaking:** `content list --detail-level` option, along with its `short`, `extended`, and `full` levels. `content list` now always produces a curated summary. Per-item detail (arguments, inputs, outputs) is available through the `content describe` command.
+
+### Fixed
+
+- `content get-detached` now returns only the content items that are actually detached. The previous query returned all system items, so the command reported every system script (or playbook) as detached instead of just the detached ones. Results are now filtered on each item's `detached` field.
+
+## [2.3.0] - 2026-06-04
+
+### Added
+
 - `execute command NAME [ARGS]...` runs an automation script or integration command against XSOAR, in the user's playground by default or a specific case with `--case-id`. See the [execute README](src/xsoar_cli/commands/execute/README.md) for details.
 - `execute playbook NAME` starts a playbook in the user's playground, or a specific case with `--case-id`. See the [execute README](src/xsoar_cli/commands/execute/README.md) for details.
 

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.3.0
+Version: 2.4.0
 Summary: A command-line interface for managing Palo Alto Networks XSOAR (Cortex XSOAR)
 Project-URL: Documentation, https://github.com/tlium/xsoar-cli#readme
 Project-URL: Issues, https://github.com/tlium/xsoar-cli/issues

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.3.0'
-__version_tuple__ = version_tuple = (2, 3, 0)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
 
 __commit_id__ = commit_id = None

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/pyproject.toml

@@ -68,6 +68,10 @@ exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.ruff]
+line-length = 140
+extend-exclude = ["tests/mock_content"]
+
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/src/xsoar_cli/commands/content/README.md

@@ -4,42 +4,70 @@ Inspect and manage content items on your XSOAR server.
 
 ## Get Detached
 
-List detached content items. Detached items are content items that are not associated with any installed content pack. Output is JSON formatted with 4-space indentation.
+List detached content items. Detached items are content items that have been modified on the server and are no longer in sync with the installed content pack.
+
+The output is a human-readable summary: a count followed by one line per item in the form `<name> (ID: <id>)`. When no detached items are found, the output is `No detached <type> found` (for example `No detached scripts found`). This applies to both `--type scripts` and `--type playbooks`.
 
 **Syntax:** `xsoar-cli content get-detached [OPTIONS]`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
-- `--type [scripts|playbooks|all]` - Type of content items to retrieve (default: all)
+- `--type [scripts|playbooks|all]` - Type of content items to retrieve (required)
 
 **Examples:**
 ```
-xsoar-cli content get-detached
-xsoar-cli content get-detached --environment prod
 xsoar-cli content get-detached --type scripts
-xsoar-cli content get-detached --type playbooks --environment dev
+xsoar-cli content get-detached --type playbooks
+xsoar-cli content get-detached --type all
+xsoar-cli content get-detached --type scripts --environment prod
 ```
 
 ## List
 
-List available content items. Enumerates commands, playbooks and scripts available on the server. Output is JSON formatted with 4-space indentation.
+List available content items. Enumerates commands, playbooks and scripts available on the server. Designed for discovery: a quick, scannable overview of what content exists, primarily to help humans and AI agents identify relevant items before working with them.
+
+By default the output is a human-readable table. Use `--output-format json` for machine-readable output, or `--output-format plain` for tab-separated values that are easy to pipe to tools like `grep`.
 
 **Syntax:** `xsoar-cli content list [OPTIONS]`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
 - `--type [scripts|playbooks|commands|all]` - Type of content items to list (default: all)
-- `--detail-level [short|extended|full]` - Amount of detail in the output (default: short)
+- `--search TEXT` - Case-insensitive substring filter on item id, name, and description
+- `--output-format [table|json|plain]` - Output format (default: table)
 
 **Examples:**
 ```
 xsoar-cli content list
 xsoar-cli content list --environment prod
 xsoar-cli content list --type commands
-xsoar-cli content list --type commands --detail-level extended
+xsoar-cli content list --type commands --search slack
+xsoar-cli content list --type commands --output-format json
+xsoar-cli content list --type scripts --output-format plain
 xsoar-cli content list --type playbooks --environment dev
 ```
 
+## Describe
+
+Describe a single content item in detail. Looks up one script, playbook, or command by name and shows its description, arguments, and inputs/outputs. Commands also show the integration brand and its configured instances (name and state). Use this after `content list` to get the detail needed to actually use an item.
+
+The lookup is case-insensitive. Scripts match on id, playbooks match on id or name (so a custom playbook with a UUID id resolves by its human-readable name), and commands match on the command name.
+
+**Syntax:** `xsoar-cli content describe --type TYPE NAME`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--type [script|playbook|command]` - Type of content item to describe (required)
+- `--output-format [table|json]` - Output format (default: table)
+
+**Examples:**
+```
+xsoar-cli content describe --type command servicenow-get-record
+xsoar-cli content describe --type script AddDNBHostIndicatorToCase
+xsoar-cli content describe --type playbook "Phishing Investigation - Generic v2"
+xsoar-cli content describe --type command servicenow-get-record --output-format json
+```
+
 ## Download
 
 Download a content item by name from the XSOAR server.

{xsoar_cli-2.3.0 → xsoar_cli-2.4.0}/src/xsoar_cli/commands/content/commands.py

@@ -1,4 +1,3 @@
-import json
 import logging
 import pathlib
 import subprocess
@@ -7,8 +6,9 @@ from typing import TYPE_CHECKING
 import click
 
 from xsoar_cli.utilities.config_file import get_xsoar_config, load_config
-from xsoar_cli.utilities.content import DETAIL_LEVELS, filter_content
+from xsoar_cli.utilities.content import describe_item, filter_content, format_detached_summary, search_content
 from xsoar_cli.utilities.download_content_handlers import HANDLERS, resolve_output_path
+from xsoar_cli.utilities.output import DESCRIBE_OUTPUT_FORMATS, OUTPUT_FORMATS, format_content_output, format_describe
 from xsoar_cli.utilities.validators import validate_xsoar_connectivity
 
 if TYPE_CHECKING:
@@ -28,7 +28,7 @@ def content() -> None:
 @click.option(
     "--type",
     "content_type",
-    type=click.Choice(["scripts", "playbooks"], case_sensitive=False),
+    type=click.Choice(["scripts", "playbooks", "all"], case_sensitive=False),
     required=True,
     help="Type of content items to retrieve.",
 )
@@ -39,9 +39,13 @@ def get_detached(ctx: click.Context, environment: str | None, content_type: str)
     """List detached content items."""
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
-    response = xsoar_client.content.get_detached(content_type)
-    data = json.loads(response)
-    click.echo(json.dumps(data, indent=4))
+
+    types = ["scripts", "playbooks"] if content_type == "all" else [content_type]
+    sections = []
+    for t in types:
+        items = xsoar_client.content.get_detached(t)
+        sections.append(format_detached_summary(items, t))
+    click.echo("\n\n".join(sections))
 
 
 # We name the command in the decorator here to avoid shadowing the builtin list.
@@ -56,16 +60,21 @@ def get_detached(ctx: click.Context, environment: str | None, content_type: str)
     help="Type of content items to list.",
 )
 @click.option(
-    "--detail-level",
-    type=click.Choice(DETAIL_LEVELS, case_sensitive=False),
-    default="short",
+    "--search",
+    default=None,
+    help="Case-insensitive substring filter on item id, name, and description.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(OUTPUT_FORMATS, case_sensitive=False),
+    default="table",
     show_default=True,
-    help="Amount of detail to include in the output.",
+    help="Output format. Use 'json' for machine-readable output.",
 )
 @click.pass_context
 @load_config
 @validate_xsoar_connectivity
-def list_content(ctx: click.Context, environment: str | None, content_type: str, detail_level: str) -> None:
+def list_content(ctx: click.Context, environment: str | None, content_type: str, search: str | None, output_format: str) -> None:
     """
     List available content items. Enumerates commands, playbooks and scripts
     available on the server, primarily to facilitate better AI generated
@@ -73,16 +82,59 @@ def list_content(ctx: click.Context, environment: str | None, content_type: str,
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
     json_blob = xsoar_client.content.list(content_type)
-    if detail_level == "full":
-        click.echo(json.dumps(json_blob, indent=4))
-        ctx.exit(0)
 
     # Individual type calls return a bare list, normalize to dict for filter_content.
     if isinstance(json_blob, list):
         json_blob = {content_type: json_blob}
 
-    filtered = filter_content(json_blob, detail_level=detail_level)
-    click.echo(json.dumps(filtered, indent=4))
+    filtered = filter_content(json_blob)
+    if search:
+        filtered = search_content(filtered, search)
+        if not filtered:
+            click.echo(f"No content matching '{search}' found.")
+            return
+
+    click.echo(format_content_output(filtered, output_format=output_format))
+
+
+@click.command()
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option(
+    "--type",
+    "content_type",
+    type=click.Choice(["script", "playbook", "command"], case_sensitive=False),
+    required=True,
+    help="Type of content item to describe.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(DESCRIBE_OUTPUT_FORMATS, case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format. Use 'json' for machine-readable output.",
+)
+@click.argument("name", type=str)
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def describe(ctx: click.Context, environment: str | None, content_type: str, output_format: str, name: str) -> None:
+    """Describe a single content item in detail.
+
+    Looks up one script, playbook, or command by name and shows its
+    description, arguments, and inputs/outputs. Commands also show the
+    integration brand and its configured instances. Use this after
+    'content list' to get the detail needed to actually use an item.
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    raw = xsoar_client.content.describe(content_type, name)
+    if raw is None:
+        click.echo(f"Error: {content_type} '{name}' not found")
+        ctx.exit(1)
+        return
+
+    item = describe_item(content_type, raw)
+    click.echo(format_describe(content_type, item, output_format=output_format))
 
 
 @click.command()
@@ -175,4 +227,5 @@ def download(ctx: click.Context, environment: str | None, content_type: str, out
 
 content.add_command(get_detached)
 content.add_command(list_content)
+content.add_command(describe)
 content.add_command(download)

xsoar_cli-2.4.0/src/xsoar_cli/utilities/content.py

@@ -0,0 +1,303 @@
+"""Helpers for filtering verbose XSOAR content responses.
+
+The raw JSON returned by xsoar_client.content.list() contains far more detail
+than downstream consumers (especially LLM-based tooling) need. The functions
+in this module strip each content type down to the fields that matter while
+keeping the output structure extensible.
+
+``content list`` uses the ``summarize_*`` functions to produce a compact
+id/comment summary per item, designed for discovery where a consumer scans
+the list to identify relevant items.
+
+The ``filter_*`` functions reduce each item to its actionable detail
+(arguments, inputs, outputs). They are reserved for the ``content describe``
+command, which presents a single item in depth.
+"""
+
+from __future__ import annotations
+
+# -- Scripts -----------------------------------------------------------------
+
+
+def summarize_scripts(scripts: list[dict]) -> list[dict]:
+    """Return an id + comment summary for each script.
+
+    This is the most compact representation, suitable for discovery queries
+    where the consumer only needs to identify scripts by name and purpose.
+    """
+    return [
+        {
+            "id": script.get("id", ""),
+            "comment": script.get("comment", ""),
+        }
+        for script in scripts
+    ]
+
+
+def filter_scripts(scripts: list[dict]) -> list[dict]:
+    """Return a detailed (but still filtered) representation of each script.
+
+    Keeps ``id``, ``comment``, and ``arguments`` (with each argument reduced
+    to ``name``, ``required``, ``deprecated``, ``description``).
+    Scripts whose ``arguments`` value is ``None`` get an empty list.
+    """
+    argument_keys = ("name", "required", "deprecated", "description")
+    filtered: list[dict] = []
+
+    for script in scripts:
+        arguments = script.get("arguments") or []
+        filtered.append(
+            {
+                "id": script.get("id", ""),
+                "comment": script.get("comment", ""),
+                "arguments": [{key: arg.get(key) for key in argument_keys} for arg in arguments],
+            }
+        )
+
+    return filtered
+
+
+def summarize_playbooks(playbooks: list[dict]) -> list[dict]:
+    """Return an id + comment summary for each playbook.
+
+    The ``comment`` field holds the playbook description and matches the
+    field name used by scripts, keeping the structure consistent across
+    content types.
+    """
+    return [
+        {
+            "id": playbook.get("id", ""),
+            "comment": playbook.get("comment", ""),
+        }
+        for playbook in playbooks
+    ]
+
+
+def filter_playbooks(playbooks: list[dict]) -> list[dict]:
+    """Return a detailed (but still filtered) representation of each playbook.
+
+    Keeps ``id``, ``comment``, ``inputs`` (reduced to ``key`` and
+    ``description``), and ``outputs`` (reduced to ``contextPath``,
+    ``description``, ``type``). The ``tasks`` blob is excluded because it
+    dominates the response size and is not useful for deciding whether to
+    use a playbook.
+    """
+    input_keys = ("key", "description")
+    output_keys = ("contextPath", "description", "type")
+    filtered: list[dict] = []
+
+    for playbook in playbooks:
+        inputs = playbook.get("inputs") or []
+        outputs = playbook.get("outputs") or []
+        filtered.append(
+            {
+                "id": playbook.get("id", ""),
+                "comment": playbook.get("comment", ""),
+                "inputs": [{key: inp.get(key) for key in input_keys} for inp in inputs],
+                "outputs": [{key: out.get(key) for key in output_keys} for out in outputs],
+            }
+        )
+
+    return filtered
+
+
+def _group_commands_by_brand(instances: list[dict]) -> list[dict]:
+    """Deduplicate integration instances by brand.
+
+    The raw ``/user/commands`` response contains one entry per integration
+    instance. When the same brand is configured with multiple instances the
+    command definitions are identical. Grouping by brand removes this
+    duplication and keeps the output focused on what commands are available
+    rather than how many instances exist.
+    """
+    seen: dict[str, dict] = {}
+    for instance in instances:
+        brand = instance.get("brand", "")
+        if brand not in seen:
+            seen[brand] = instance
+    return list(seen.values())
+
+
+def summarize_commands(instances: list[dict]) -> list[dict]:
+    """Return a brand + command summary for each integration.
+
+    Deduplicates by brand and reduces each command to ``name`` and
+    ``description``. Returning objects (rather than plain name strings)
+    keeps the structure consistent with ``filter_commands`` so formatters
+    do not need to handle both shapes.
+    """
+    grouped = _group_commands_by_brand(instances)
+    return [
+        {
+            "brand": instance.get("brand", ""),
+            "commands": [
+                {
+                    "name": cmd.get("name", ""),
+                    "description": cmd.get("description", ""),
+                }
+                for cmd in instance.get("commands") or []
+            ],
+        }
+        for instance in grouped
+    ]
+
+
+def filter_commands(instances: list[dict]) -> list[dict]:
+    """Return a detailed (but still filtered) representation of each integration's commands.
+
+    Deduplicates by brand. Keeps each command's ``name``, ``description``,
+    ``arguments`` (reduced to ``name``, ``required``, ``deprecated``,
+    ``description``), and ``outputs`` (reduced to ``contextPath``,
+    ``description``, ``type``).
+    """
+    argument_keys = ("name", "required", "deprecated", "description")
+    output_keys = ("contextPath", "description", "type")
+    grouped = _group_commands_by_brand(instances)
+    filtered: list[dict] = []
+
+    for instance in grouped:
+        commands: list[dict] = []
+        for cmd in instance.get("commands") or []:
+            arguments = cmd.get("arguments") or []
+            outputs = cmd.get("outputs") or []
+            commands.append(
+                {
+                    "name": cmd.get("name", ""),
+                    "description": cmd.get("description", ""),
+                    "arguments": [{key: arg.get(key) for key in argument_keys} for arg in arguments],
+                    "outputs": [{key: out.get(key) for key in output_keys} for out in outputs],
+                }
+            )
+        filtered.append(
+            {
+                "brand": instance.get("brand", ""),
+                "commands": commands,
+            }
+        )
+
+    return filtered
+
+
+# -- Detached content --------------------------------------------------------
+
+
+def format_detached_summary(items: list[dict], content_type: str) -> str:
+    """Format a human-readable summary of detached content items.
+
+    *items* is the list of content records returned for a single content type
+    (for example the ``scripts`` list from the detached automation search).
+    *content_type* is the plural label used in the output (for example
+    ``"scripts"``).
+
+    When *items* is empty, returns ``"No detached <content_type> found"``.
+    Otherwise returns a header line with the count followed by one indented
+    line per item in the form ``<name> (ID: <id>)``.
+    """
+    if not items:
+        return f"No detached {content_type} found"
+
+    lines = [f"Found {len(items)} detached {content_type}:"]
+    lines.extend(f"  {item.get('name', '')} (ID: {item.get('id', '')})" for item in items)
+    return "\n".join(lines)
+
+
+def filter_content(raw: dict) -> dict:
+    """Produce a compact id/comment summary for each content type in *raw*.
+
+    ``raw`` is the dict returned by ``xsoar_client.content.list()`` and may
+    contain any combination of ``scripts``, ``playbooks``, and ``commands``
+    keys depending on the requested type.
+    """
+    result: dict = {}
+
+    if "scripts" in raw:
+        result["scripts"] = summarize_scripts(raw["scripts"])
+
+    if "playbooks" in raw:
+        result["playbooks"] = summarize_playbooks(raw["playbooks"])
+
+    if "commands" in raw:
+        result["commands"] = summarize_commands(raw["commands"])
+
+    return result
+
+
+_SEARCH_FIELDS = ("id", "name", "comment", "description")
+
+
+def _item_matches(item: dict, term: str) -> bool:
+    """Return True if *term* is a substring of any searchable field on *item*.
+
+    The match is case-insensitive and checks ``id``, ``name``, ``comment``,
+    and ``description`` (whichever are present). *term* is expected to be
+    already lowercased.
+    """
+    return any(term in str(item.get(field, "")).lower() for field in _SEARCH_FIELDS)
+
+
+def search_content(summary: dict, term: str) -> dict:
+    """Filter a content summary down to items matching *term*.
+
+    *summary* is the dict produced by ``filter_content()``. The match is a
+    case-insensitive substring test against each item's ``id``, ``name``,
+    ``comment``, and ``description`` fields (whichever are present).
+
+    For scripts and playbooks, non-matching items are dropped. For commands,
+    only matching commands are kept within each brand group, and brand groups
+    left with no matching commands are dropped. Content types left with no
+    matches are omitted from the result entirely.
+
+    When *term* is empty, the summary is returned unchanged.
+    """
+    if not term:
+        return summary
+
+    needle = term.lower()
+    result: dict = {}
+
+    for content_type in ("scripts", "playbooks"):
+        items = summary.get(content_type)
+        if items is None:
+            continue
+        matches = [item for item in items if _item_matches(item, needle)]
+        if matches:
+            result[content_type] = matches
+
+    if "commands" in summary:
+        groups: list[dict] = []
+        for group in summary["commands"]:
+            matching = [cmd for cmd in group.get("commands", []) if _item_matches(cmd, needle)]
+            if matching:
+                groups.append({"brand": group.get("brand", ""), "commands": matching})
+        if groups:
+            result["commands"] = groups
+
+    return result
+
+
+def describe_item(item_type: str, raw: dict) -> dict:
+    """Reduce a single raw content item to its actionable detail.
+
+    *item_type* is ``script``, ``playbook``, or ``command`` (singular).
+    *raw* is the record returned by ``Content.describe()``. For commands the
+    raw record wraps the command in ``{brand, instances, command}``; the
+    reduced result flattens that into the command fields plus ``brand`` and
+    ``instances``.
+    """
+    if item_type == "script":
+        return filter_scripts([raw])[0]
+    if item_type == "playbook":
+        return filter_playbooks([raw])[0]
+    if item_type == "command":
+        brand = raw.get("brand", "")
+        instances = raw.get("instances", [])
+        reduced = filter_commands([{"brand": brand, "commands": [raw.get("command", {})]}])[0]["commands"][0]
+        return {
+            "name": reduced["name"],
+            "brand": brand,
+            "instances": instances,
+            "description": reduced["description"],
+            "arguments": reduced["arguments"],
+            "outputs": reduced["outputs"],
+        }
+    raise ValueError(f"Invalid value {item_type=}")