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

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

@@ -6,12 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-06-17
+
 ### 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.
+- `case get-context CASENUMBER` command. Retrieves the investigation context tree for a case as JSON, matching `demisto.context()` at runtime. The incident record is not merged in. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
+- `case get-entry ENTRY_ID` command. Retrieves a single War Room entry by its full ID (e.g. `112@153483`) as JSON. The case ID is derived from the entry ID. Exits non-zero with a clear message when the entry ID is malformed or the entry is not found. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
+- `case get-entries CASENUMBER` command. Retrieves all War Room entries for a case as a JSON array, or an empty array when the case has no entries. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
 
 ### Changed
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.4.0
+Version: 2.4.1
 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.4.0 → xsoar_cli-2.4.1}/_version.py

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

{xsoar_cli-2.4.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/case/README.md

@@ -17,6 +17,53 @@ xsoar-cli case get 312412
 xsoar-cli case get --environment prod 312412
 ```
 
+## Get Context
+
+Retrieve the investigation context tree for a single case. Output is the raw context tree as JSON, matching `demisto.context()` at runtime. The incident record is not merged in.
+
+**Syntax:** `xsoar-cli case get-context [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-context 153483
+xsoar-cli case get-context --environment prod 153483
+```
+
+## Get Entry
+
+Retrieve a single War Room entry by its full ID. Output is the raw entry as JSON. The command exits non-zero with a clear message when no entry with that ID exists in the case.
+
+`ENTRY_ID` is the full entry ID as shown in the GUI, in the form `<n>@<case-id>` (e.g. `112@153483`). The case ID is taken from the entry ID, so it does not need to be supplied separately.
+
+**Syntax:** `xsoar-cli case get-entry [OPTIONS] ENTRY_ID`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-entry 112@153483
+xsoar-cli case get-entry --environment prod 112@153483
+```
+
+## Get Entries
+
+Retrieve all War Room entries for a single case. Output is the full list of entries as a JSON array, or an empty array when the case has no entries.
+
+**Syntax:** `xsoar-cli case get-entries [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-entries 153483
+xsoar-cli case get-entries --environment prod 153483
+```
+
 ## Clone
 
 Clone a case from one environment to another. Useful for copying production cases to development environment for testing.

{xsoar_cli-2.4.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/case/commands.py

@@ -25,6 +25,19 @@ def parse_string_to_dict(input_string: str | None, delimiter: str) -> dict:
     return {key.strip(): value.strip() for key, value in valid_pairs}
 
 
+def parse_entry_id(entry_id: str) -> int:
+    """Extract the numeric case ID from a full entry ID of the form '<n>@<case-id>'.
+
+    Raises ValueError if the entry ID is not in that form.
+    """
+    parts = entry_id.split("@")
+    expected_parts = 2
+    if len(parts) != expected_parts or not parts[0].isdigit() or not parts[1].isdigit():
+        msg = f"invalid entry id '{entry_id}', expected the form <n>@<case-id> (e.g. 112@153483)"
+        raise ValueError(msg)
+    return int(parts[1])
+
+
 @click.group()
 def case() -> None:
     """Create, retrieve, and clone cases"""
@@ -210,6 +223,99 @@ def create(  # noqa: PLR0913
     click.echo(f"Created XSOAR case {case_id}")
 
 
+@click.command(name="get-context")
+@click.argument("casenumber", type=int)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_context(ctx: click.Context, casenumber: int, environment: str | None) -> None:
+    """Retrieve the investigation context tree for a single case.
+
+    CASENUMBER is the numeric case ID to look up. Output is the raw context
+    tree as JSON, matching demisto.context() at runtime.
+
+    Usage examples:
+
+    xsoar-cli case get-context 153483
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_context(casenumber)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.command(name="get-entry")
+@click.argument("entry_id", type=str)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_entry(ctx: click.Context, entry_id: str, environment: str | None) -> None:
+    """Retrieve a single War Room entry by its full ID.
+
+    ENTRY_ID is the full entry ID as shown in the GUI, in the form
+    <n>@<case-id> (e.g. 112@153483). The case ID is taken from the entry ID, so
+    it does not need to be supplied separately. Output is the raw entry as JSON.
+
+    Usage examples:
+
+    xsoar-cli case get-entry 112@153483
+    """
+    try:
+        casenumber = parse_entry_id(entry_id)
+    except ValueError as ex:
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_entry(casenumber, entry_id)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    except ValueError as ex:
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.command(name="get-entries")
+@click.argument("casenumber", type=int)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_entries(ctx: click.Context, casenumber: int, environment: str | None) -> None:
+    """Retrieve all War Room entries for a single case.
+
+    CASENUMBER is the numeric case ID. Output is the full list of entries as a
+    JSON array, or an empty array when the case has no entries.
+
+    Usage examples:
+
+    xsoar-cli case get-entries 153483
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_entries(casenumber)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
 case.add_command(get)
 case.add_command(clone)
 case.add_command(create)
+case.add_command(get_context)
+case.add_command(get_entry)
+case.add_command(get_entries)

xsoar_cli-2.4.1/src/xsoar_cli/xsoar_client/cases.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .constants import INVESTIGATION_PAGE_SIZE
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+class Cases:
+    def __init__(self, client: Client) -> None:
+        self.client = client
+
+    def get(self, case_id: int) -> dict:
+        """Fetches a case by ID."""
+        endpoint = f"/incident/load/{case_id}"
+        response = self.client.make_request(endpoint=endpoint, method="GET")
+        response.raise_for_status()
+        return response.json()
+
+    def create(self, data: dict) -> dict:
+        """Creates a new case."""
+        endpoint = self.client.resolve_endpoint(v6="/incident", v8="/xsoar/public/v1/incident")
+        response = self.client.make_request(endpoint=endpoint, json=data, method="POST")
+        response.raise_for_status()
+        return response.json()
+
+    def get_context(self, case_id: int) -> dict:
+        """Fetches the investigation context tree for a case, verbatim.
+
+        Returns the raw POST /investigation/<id>/context response, which matches
+        demisto.context() at runtime. The incident record is not merged in.
+
+        The body query '${.}' is a DT expression meaning "the entire context
+        root", so the full context tree is returned.
+        """
+        endpoint = f"/investigation/{case_id}/context"
+        response = self.client.make_request(endpoint=endpoint, method="POST", json={"query": "${.}"})
+        response.raise_for_status()
+        return response.json()
+
+    def get_entry(self, case_id: int, entry_id: str) -> dict:
+        """Fetches a single War Room entry by its full ID (e.g. '112@153483').
+
+        XSOAR has no per-entry endpoint, so the full War Room history is fetched
+        via POST /investigation/<id> and the entry with the matching id is
+        returned verbatim. Raises ValueError if no entry with that id exists.
+        """
+        for entry in self._fetch_entries(case_id):
+            if entry.get("id") == entry_id:
+                return entry
+        msg = f"Entry '{entry_id}' not found in case {case_id}"
+        raise ValueError(msg)
+
+    def get_entries(self, case_id: int) -> list[dict]:
+        """Fetches all War Room entries for a case, verbatim.
+
+        Returns the full entries list from POST /investigation/<id>. An empty
+        list is returned when the case has no entries.
+        """
+        return self._fetch_entries(case_id)
+
+    def _fetch_entries(self, case_id: int) -> list[dict]:
+        """Fetches the full War Room entry history for a case.
+
+        XSOAR has no per-entry endpoint, so the whole history is retrieved with
+        a single POST /investigation/<id> call and the entries list is returned
+        verbatim.
+        """
+        data, _, _ = self.client.demisto_py_instance.generic_request(
+            path=f"/investigation/{case_id}",
+            method="POST",
+            body={"pageSize": INVESTIGATION_PAGE_SIZE},
+            content_type="application/json",
+            response_type=object,
+        )
+        return data.get("entries") or []

xsoar_cli-2.4.1/src/xsoar_cli/xsoar_client/constants.py

@@ -0,0 +1,8 @@
+"""Shared constants for the xsoar_client package."""
+
+XSOAR_OLD_VERSION = 6
+HTTP_CALL_TIMEOUT = 30
+
+# Page size requested when fetching investigation entries via POST /investigation/<id>.
+# Set high so that all War Room entries are returned in a single response.
+INVESTIGATION_PAGE_SIZE = 1000

{xsoar_cli-2.4.0 → xsoar_cli-2.4.1}/src/xsoar_cli/xsoar_client/execution.py

@@ -4,6 +4,8 @@ import logging
 import time
 from typing import TYPE_CHECKING
 
+from .constants import INVESTIGATION_PAGE_SIZE
+
 if TYPE_CHECKING:
     from .client import Client
 
@@ -23,11 +25,6 @@ DEFAULT_SYNC_TIMEOUT = 30
 # result entries.
 SYNC_POLL_INTERVAL = 2
 
-# Page size requested when fetching investigation entries during polling. The
-# playground accumulates history over time, so this is set high to ensure a
-# freshly created result entry is included in the response.
-INVESTIGATION_PAGE_SIZE = 1000
-
 
 def _format_arg_value(value: str) -> str:
     """Format a single argument value for a War Room command string.

{xsoar_cli-2.4.0 → xsoar_cli-2.4.1}/tests/cli/conftest.py

@@ -272,9 +272,10 @@ def mock_execute_env(mock_config_file) -> Iterator[types.SimpleNamespace]:  # no
 def mock_case_env(mock_config_file, make_case_response, make_case_create_response) -> Iterator[types.SimpleNamespace]:  # noqa: ANN001
     """Mock environment for ``case`` commands.
 
-    Patches ``Cases.get`` and ``Cases.create`` with default success responses.
-    The mocks are exposed on the yielded namespace so tests can override
-    return values or side effects as needed.
+    Patches ``Cases.get``, ``Cases.create``, ``Cases.get_context``,
+    ``Cases.get_entry``, and ``Cases.get_entries`` with default success
+    responses. The mocks are exposed on the yielded namespace so tests can
+    override return values or side effects as needed.
     """
     import types as _types
 
@@ -282,13 +283,22 @@ def mock_case_env(mock_config_file, make_case_response, make_case_create_respons
         patch("xsoar_cli.xsoar_client.client.Client.test_connectivity", return_value=True) as mock_conn,
         patch("xsoar_cli.xsoar_client.cases.Cases.get") as mock_get,
         patch("xsoar_cli.xsoar_client.cases.Cases.create") as mock_create,
+        patch("xsoar_cli.xsoar_client.cases.Cases.get_context") as mock_get_context,
+        patch("xsoar_cli.xsoar_client.cases.Cases.get_entry") as mock_get_entry,
+        patch("xsoar_cli.xsoar_client.cases.Cases.get_entries") as mock_get_entries,
     ):
         mock_get.return_value = make_case_response()
         mock_create.return_value = make_case_create_response()
+        mock_get_context.return_value = {"playbook_name": "My Playbook", "File": []}
+        mock_get_entry.return_value = {"id": "112@153483", "contents": "entry data"}
+        mock_get_entries.return_value = [{"id": "112@153483", "contents": "entry data"}]
         ns = _types.SimpleNamespace(
             config=mock_config_file,
             connectivity=mock_conn,
             get=mock_get,
             create=mock_create,
+            get_context=mock_get_context,
+            get_entry=mock_get_entry,
+            get_entries=mock_get_entries,
         )
         yield ns

xsoar_cli-2.4.1/tests/cli/test_case.py

@@ -0,0 +1,123 @@
+"""CLI integration tests for the ``case`` command group."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tests.cli.conftest import InvokeHelper
+
+
+class TestCaseGroup:
+    """The bare ``case`` command and its help output."""
+
+    def test_shows_help(self, invoke: InvokeHelper) -> None:
+        result = invoke(["case"])
+        assert result.exit_code == 0
+
+    def test_help_flag(self, invoke: InvokeHelper) -> None:
+        result = invoke(["case", "--help"])
+        assert result.exit_code == 0
+
+
+class TestCaseGet:
+    """Tests for ``case get``."""
+
+    def test_get_case_success(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get", "152230"])
+        assert result.exit_code == 0
+
+    def test_get_case_http_error(self, invoke: InvokeHelper, mock_case_env, make_http_error) -> None:
+        mock_case_env.get.side_effect = make_http_error(400, text="Bad Request")
+        result = invoke(["case", "get", "152230"])
+        assert result.exit_code == 1
+
+
+class TestCaseCreate:
+    """Tests for ``case create``."""
+
+    def test_create_case_success(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "create"])
+        assert result.exit_code == 0
+
+
+class TestCaseClone:
+    """Tests for ``case clone``."""
+
+    def test_clone_missing_options(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "clone", "152230"])
+        assert result.exit_code == 2
+
+    def test_clone_with_bogus_environments(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "clone", "--dest", "bogus", "--source", "bogus", "152230"])
+        assert result.exit_code == 1
+
+
+class TestCaseGetContext:
+    """Tests for ``case get-context``."""
+
+    def test_get_context_success(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-context", "153483"])
+        assert result.exit_code == 0
+        mock_case_env.get_context.assert_called_once_with(153483)
+
+    def test_get_context_http_error(self, invoke: InvokeHelper, mock_case_env, make_http_error) -> None:
+        mock_case_env.get_context.side_effect = make_http_error(404, text="Not Found")
+        result = invoke(["case", "get-context", "153483"])
+        assert result.exit_code == 1
+
+
+class TestCaseGetEntry:
+    """Tests for ``case get-entry``."""
+
+    def test_get_entry_success(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-entry", "112@153483"])
+        assert result.exit_code == 0
+        mock_case_env.get_entry.assert_called_once_with(153483, "112@153483")
+
+    def test_get_entry_not_found(self, invoke: InvokeHelper, mock_case_env) -> None:
+        mock_case_env.get_entry.side_effect = ValueError("Entry '999@153483' not found in case 153483")
+        result = invoke(["case", "get-entry", "999@153483"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+    def test_get_entry_http_error(self, invoke: InvokeHelper, mock_case_env, make_http_error) -> None:
+        mock_case_env.get_entry.side_effect = make_http_error(400, text="Bad Request")
+        result = invoke(["case", "get-entry", "112@153483"])
+        assert result.exit_code == 1
+
+    def test_get_entry_missing_entry_id_argument(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-entry"])
+        assert result.exit_code == 2
+
+    def test_get_entry_malformed_entry_id(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-entry", "112"])
+        assert result.exit_code == 1
+        assert "invalid entry id" in result.output
+        mock_case_env.get_entry.assert_not_called()
+
+    def test_get_entry_non_numeric_entry_number(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-entry", "12INVALID21@1234"])
+        assert result.exit_code == 1
+        assert "invalid entry id" in result.output
+        mock_case_env.get_entry.assert_not_called()
+
+
+class TestCaseGetEntries:
+    """Tests for ``case get-entries``."""
+
+    def test_get_entries_success(self, invoke: InvokeHelper, mock_case_env) -> None:
+        result = invoke(["case", "get-entries", "153483"])
+        assert result.exit_code == 0
+        mock_case_env.get_entries.assert_called_once_with(153483)
+
+    def test_get_entries_empty(self, invoke: InvokeHelper, mock_case_env) -> None:
+        mock_case_env.get_entries.return_value = []
+        result = invoke(["case", "get-entries", "153483"])
+        assert result.exit_code == 0
+        assert result.output.strip() == "[]"
+
+    def test_get_entries_http_error(self, invoke: InvokeHelper, mock_case_env, make_http_error) -> None:
+        mock_case_env.get_entries.side_effect = make_http_error(404, text="Not Found")
+        result = invoke(["case", "get-entries", "153483"])
+        assert result.exit_code == 1

xsoar_cli-2.4.1/tests/unit/test_case_commands.py

@@ -0,0 +1,39 @@
+"""Unit tests for helpers in ``xsoar_cli.commands.case.commands``."""
+
+from __future__ import annotations
+
+import pytest
+
+from xsoar_cli.commands.case.commands import parse_entry_id
+
+
+class TestParseEntryId:
+    def test_valid_entry_id_returns_case_id(self) -> None:
+        assert parse_entry_id("112@153483") == 153483
+
+    def test_multi_digit_entry_number(self) -> None:
+        assert parse_entry_id("9@7") == 7
+
+    def test_missing_at_separator_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("112")
+
+    def test_empty_entry_number_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("@153483")
+
+    def test_non_numeric_entry_number_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("12INVALID21@1234")
+
+    def test_empty_case_id_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("112@")
+
+    def test_non_numeric_case_id_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("112@abc")
+
+    def test_too_many_parts_raises(self) -> None:
+        with pytest.raises(ValueError, match="invalid entry id"):
+            parse_entry_id("112@153483@extra")