howler-client 2.4.0.dev242__tar.gz → 2.4.0.dev286__tar.gz

{howler_client-2.4.0.dev242 → howler_client-2.4.0.dev286}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-client
-Version: 2.4.0.dev242
+Version: 2.4.0.dev286
 Summary: The Howler client library facilitates issuing requests to Howler
 License: MIT
 License-File: LICENSE

{howler_client-2.4.0.dev242 → howler_client-2.4.0.dev286}/howler_client/client.py

@@ -2,11 +2,11 @@ import sys
 
 from howler_client.common.utils import walk_api_path
 from howler_client.connection import Connection
-from howler_client.module.bundle import Bundle
 from howler_client.module.help import Help
 from howler_client.module.hit import Hit
 from howler_client.module.search import Search
 from howler_client.module.user import User
+from howler_client.module.v2 import V2
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -23,8 +23,8 @@ class Client(object):
         self.help = Help(self._connection)
         self.search = Search(self._connection)
         self.hit = Hit(self._connection, self.search)
-        self.bundle = Bundle(self._connection, self.hit)
         self.user = User(self._connection)
+        self.v2 = V2(self._connection)
 
         paths: list[str] = []
         walk_api_path(self, [""], paths)

{howler_client-2.4.0.dev242 → howler_client-2.4.0.dev286}/howler_client/common/utils.py

@@ -61,6 +61,21 @@ def api_path(prefix, *args, **kw):
     return f"{path}?{params}"
 
 
+def api_path_v2(prefix, *args, **kw):
+    """Calculate the API path for v2 endpoints as shown:
+
+    /api/v2/<prefix>/[arg1/[arg2/[...]]][?k1=v1[...]]
+    """
+    path = "/".join(["api", "v2", prefix] + list(args))
+
+    params_tuples = kw.pop("params_tuples", [])
+    params = "&".join([_join_kw(kw)] + [_join_param(*e) for e in params_tuples if _param_ok(e)])
+    if not params:
+        return path
+
+    return f"{path}?{params}"
+
+
 def stream_output(output):
     "Stream the output of a response"
 

howler_client-2.4.0.dev286/howler_client/module/v2/__init__.py

@@ -0,0 +1,30 @@
+"""V2 API module container.
+
+Provides access to v2-only endpoints: ``case``, ``ingest``, and ``search``.
+"""
+
+import sys
+from typing import TYPE_CHECKING
+
+from howler_client.module.v2.case import Case
+from howler_client.module.v2.ingest import Ingest
+from howler_client.module.v2.search import SearchV2
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from howler_client import Connection
+
+
+class V2(object):
+    """Access v2 API endpoints."""
+
+    def __init__(self: Self, connection: "Connection"):
+        self._connection = connection
+
+        self.case = Case(connection)
+        self.ingest = Ingest(connection)
+        self.search = SearchV2(connection)

howler_client-2.4.0.dev286/howler_client/module/v2/case.py

@@ -0,0 +1,177 @@
+"""Client module for the v2 Case API."""
+
+import sys
+from typing import TYPE_CHECKING, Any, Literal
+
+from howler_client.common.utils import api_path_v2
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from howler_client import Connection
+
+
+class Case(object):
+    """Operations for managing cases via the v2 API."""
+
+    def __init__(self: Self, connection: "Connection"):
+        self._connection = connection
+
+    def __call__(self: Self, case_id: str) -> dict[str, Any]:
+        """Return a case by ID.
+
+        Args:
+            case_id: Unique identifier of the case.
+
+        Returns:
+            The case data.
+        """
+        return self._connection.get(api_path_v2("case", case_id))
+
+    def create(self: Self, case_data: dict[str, Any]) -> dict[str, Any]:
+        """Create a new case.
+
+        Args:
+            case_data: Dictionary with at least ``title`` and ``summary``.
+
+        Returns:
+            The created case data.
+        """
+        return self._connection.post(api_path_v2("case/"), json=case_data)
+
+    def update(self: Self, case_id: str, updates: dict[str, Any]) -> dict[str, Any]:
+        """Update fields on an existing case.
+
+        Args:
+            case_id: ID of the case to update.
+            updates: Dictionary of fields to update.
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.put(api_path_v2("case", case_id), json=updates)
+
+    def delete(self: Self, case_ids: list[str]) -> None:
+        """Delete one or more cases.
+
+        Args:
+            case_ids: List of case IDs to delete.
+        """
+        return self._connection.delete(api_path_v2("case/"), json=case_ids)
+
+    def hide(self: Self, case_ids: list[str]) -> dict[Literal["success"], bool]:
+        """Hide one or more cases.
+
+        Args:
+            case_ids: List of case IDs to hide.
+
+        Returns:
+            Whether the operation succeeded.
+        """
+        return self._connection.post(api_path_v2("case/hide"), json=case_ids)
+
+    def append_item(
+        self: Self,
+        case_id: str,
+        item_type: str,
+        value: str,
+        path: str | None = None,
+        name: str | None = None,
+        parent: str | None = None,
+    ) -> dict[str, Any]:
+        """Append an item to a case.
+
+        Args:
+            case_id: ID of the case.
+            item_type: Type of item (``hit``, ``event``, ``case``, ``table``, ``lead``, or ``reference``).
+            value: The ID or reference value for the item.
+            path: Optional parent folder path for the item.
+            name: Optional display name for the item. Defaults to ``value``.
+            parent: Optional parent folder item ID. If both ``path`` and ``parent``
+                are provided, the API resolves and applies ``path``.
+
+        Returns:
+            The updated case data.
+        """
+        payload: dict[str, Any] = {
+            "type": item_type,
+            "value": value,
+            "name": name or value,
+        }
+        if parent is not None:
+            payload["parent"] = parent
+        if path is not None:
+            payload["path"] = path
+
+        return self._connection.post(
+            api_path_v2("case", case_id, "items"),
+            json=payload,
+        )
+
+    def delete_items(self: Self, case_id: str, item_ids: list[str]) -> dict[str, Any]:
+        """Remove items from a case.
+
+        Args:
+            case_id: ID of the case.
+            item_ids: List of item IDs to remove.
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.delete(api_path_v2("case", case_id, "items"), json={"ids": item_ids})
+
+    def rename_item(self: Self, case_id: str, item_id: str, new_name: str) -> dict[str, Any]:
+        """Rename an item within a case.
+
+        Args:
+            case_id: ID of the case.
+            item_id: ID identifying the item to rename.
+            new_name: New display name for the item.
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.put(
+            api_path_v2("case", case_id, "items"),
+            json={"id": item_id, "name": new_name},
+        )
+
+    def add_rule(self: Self, case_id: str, rule_data: dict[str, Any]) -> dict[str, Any]:
+        """Add a correlation rule to a case.
+
+        Args:
+            case_id: ID of the case.
+            rule_data: Rule definition (must include ``query``, ``destination``, ``author``).
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.post(api_path_v2("case", case_id, "rules"), json=rule_data)
+
+    def delete_rule(self: Self, case_id: str, rule_id: str) -> dict[str, Any]:
+        """Delete a correlation rule from a case.
+
+        Args:
+            case_id: ID of the case.
+            rule_id: ID of the rule to delete.
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.delete(api_path_v2("case", case_id, "rules", rule_id))
+
+    def update_rule(self: Self, case_id: str, rule_id: str, rule_data: dict[str, Any]) -> dict[str, Any]:
+        """Update a correlation rule on a case.
+
+        Args:
+            case_id: ID of the case.
+            rule_id: ID of the rule to update.
+            rule_data: Updated rule fields.
+
+        Returns:
+            The updated case data.
+        """
+        return self._connection.put(api_path_v2("case", case_id, "rules", rule_id), json=rule_data)

howler_client-2.4.0.dev286/howler_client/module/v2/ingest.py

@@ -0,0 +1,160 @@
+"""Client module for the v2 Ingest API."""
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any, Literal, Union
+
+from howler_client.common.utils import ClientError, api_path_v2
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from howler_client import Connection
+
+UPDATE_OPERATIONS = [
+    "SET",
+    "INC",
+    "DEC",
+    "MAX",
+    "MIN",
+    "APPEND",
+    "APPEND_IF_MISSING",
+    "REMOVE",
+    "DELETE",
+]
+
+
+class Ingest(object):
+    """Operations for ingesting records via the v2 API.
+
+    Unlike the v1 ``hit`` module, v2 ingest supports multiple indexes
+    (``hit`` and ``event``) and enqueues new records for correlation
+    processing.
+    """
+
+    def __init__(self: Self, connection: "Connection"):
+        self._connection = connection
+
+    def create(
+        self: Self,
+        index: str,
+        data: Union[dict[str, Any], list[dict[str, Any]]],
+    ) -> list[str]:
+        """Create one or more records in the given index.
+
+        Args:
+            index: Target index (``hit`` or ``event``).
+            data: A single record dict or a list of record dicts.
+
+        Returns:
+            List of created record IDs.
+        """
+        if not isinstance(data, list):
+            data = [data]
+
+        return self._connection.post(
+            api_path_v2("ingest", index),
+            data=json.dumps(data),
+            headers={"Content-Type": "application/json"},
+        )
+
+    def delete(self: Self, indexes: str, ids: list[str]) -> dict[str, Any]:
+        """Delete records across one or more indexes.
+
+        Args:
+            indexes: Comma-separated index names (e.g. ``"hit"`` or ``"hit,event"``).
+            ids: List of record IDs to delete.
+
+        Returns:
+            Dictionary with deletion results.
+        """
+        return self._connection.delete(api_path_v2("ingest", indexes), json=ids)
+
+    def validate(
+        self: Self,
+        index: str,
+        data: Union[dict[str, Any], list[dict[str, Any]]],
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Validate records against an index schema without persisting.
+
+        Args:
+            index: Target index (``hit`` or ``event``).
+            data: A single record dict or a list of record dicts.
+
+        Returns:
+            Dictionary with ``valid`` and ``invalid`` lists.
+        """
+        if not isinstance(data, list):
+            data = [data]
+
+        return self._connection.post(
+            api_path_v2("ingest", index, "validate"),
+            data=json.dumps(data),
+            headers={"Content-Type": "application/json"},
+        )
+
+    def overwrite(
+        self: Self,
+        index: str,
+        record_id: str,
+        new_data: dict[str, Any],
+        replace: bool = False,
+    ) -> dict[str, Any]:
+        """Overwrite (patch) a single record.
+
+        Args:
+            index: Index of the record (e.g. ``"hit"``).
+            record_id: ID of the record to overwrite.
+            new_data: Partial record data to merge.
+            replace: If ``True``, lists are replaced instead of merged.
+
+        Returns:
+            The updated record data.
+        """
+        if not isinstance(new_data, dict):
+            raise TypeError("new_data must be a dict.")
+
+        return self._connection.request(
+            self._connection.session.patch,
+            api_path_v2("ingest", index, record_id, "overwrite", replace=replace if replace else None),
+            lambda resp: resp.json()["api_response"],
+            json=new_data,
+        )
+
+    def update_by_query(
+        self: Self,
+        indexes: str,
+        query: str,
+        operations: list[tuple[str, str, Any]],
+    ) -> dict[Literal["success"], bool]:
+        """Bulk update records matching a query.
+
+        Args:
+            indexes: Comma-separated index names.
+            query: Lucene query selecting records to update.
+            operations: List of ``(operation, key, value)`` tuples.
+                Valid operations: SET, INC, DEC, MAX, MIN, APPEND,
+                APPEND_IF_MISSING, REMOVE, DELETE.
+
+        Returns:
+            Whether the operation succeeded.
+        """
+        if not isinstance(operations, list):
+            raise TypeError("operations must be a list.")
+
+        for op in operations:
+            if not isinstance(op, tuple):
+                raise TypeError("Each operation must be a tuple.")
+            if op[0] not in UPDATE_OPERATIONS:
+                raise ClientError(
+                    f"Invalid operation '{op[0]}' — must be one of {', '.join(UPDATE_OPERATIONS)}",
+                    400,
+                )
+
+        return self._connection.put(
+            api_path_v2("ingest", indexes, "update"),
+            json={"query": query, "operations": operations},
+        )

howler_client-2.4.0.dev286/howler_client/module/v2/search.py

@@ -0,0 +1,153 @@
+"""Client module for the v2 Search API."""
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any, Optional
+
+from howler_client.common.utils import api_path_v2
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from howler_client import Connection
+
+
+class SearchV2(object):
+    """Search operations via the v2 API.
+
+    Unlike the v1 search module, v2 supports searching across multiple
+    comma-separated indexes in a single request.
+    """
+
+    def __init__(self: Self, connection: "Connection"):
+        self._connection = connection
+
+    def __call__(
+        self: Self,
+        indexes: str,
+        query: str,
+        filters: Optional[list[str]] = None,
+        fl: Optional[str] = None,
+        offset: int = 0,
+        rows: int = 25,
+        sort: Optional[str] = None,
+        timeout: Optional[int] = None,
+        use_archive: bool = False,
+        track_total_hits: bool = False,
+        metadata: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """Search across one or more indexes.
+
+        Args:
+            indexes: Comma-separated index names (e.g. ``"hit"`` or ``"hit,event"``).
+            query: Lucene query string.
+            filters: Additional filter queries.
+            fl: Comma-separated list of fields to return.
+            offset: Result offset.
+            rows: Number of results per page.
+            sort: Sort specification (e.g. ``"event.created desc"``).
+            timeout: Maximum execution time in milliseconds.
+            use_archive: Include archived data.
+            track_total_hits: Track exact total hit count.
+            metadata: Additional features to include (e.g. ``["dossiers"]``).
+
+        Returns:
+            Search result with ``total``, ``offset``, ``rows``, ``items``.
+        """
+        body: dict[str, Any] = {"query": query, "offset": offset, "rows": rows}
+
+        if filters:
+            body["filters"] = filters
+        if fl:
+            body["fl"] = fl
+        if sort:
+            body["sort"] = sort
+        if timeout is not None:
+            body["timeout"] = timeout
+        if use_archive:
+            body["use_archive"] = True
+        if track_total_hits:
+            body["track_total_hits"] = True
+        if metadata:
+            body["metadata"] = metadata
+
+        return self._connection.post(api_path_v2("search", indexes), data=json.dumps(body))
+
+    def explain(self: Self, index: str, query: str) -> dict[str, Any]:
+        """Explain a Lucene query against an index.
+
+        Args:
+            index: Single index name (e.g. ``"hit"``).
+            query: Lucene query to explain.
+
+        Returns:
+            Explanation with ``valid`` and ``explanations`` fields.
+        """
+        return self._connection.post(api_path_v2("search", index, "explain"), json={"query": query})
+
+    def count(
+        self: Self,
+        index: str,
+        query: str,
+        filters: Optional[list[str]] = None,
+        timeout: Optional[int] = None,
+        use_archive: bool = False,
+    ) -> int:
+        """Count documents matching a query.
+
+        Args:
+            index: Single index name (e.g. ``"hit"``).
+            query: Lucene query string.
+            filters: Additional filter queries.
+            timeout: Maximum execution time in milliseconds.
+            use_archive: Include archived data.
+
+        Returns:
+            Number of matching documents.
+        """
+        body: dict[str, Any] = {"query": query}
+
+        if filters:
+            body["filters"] = filters
+        if timeout is not None:
+            body["timeout"] = timeout
+        if use_archive:
+            body["use_archive"] = True
+
+        return self._connection.post(api_path_v2("search", "count", index), json=body)["count"]
+
+    def facet(
+        self: Self,
+        indexes: str,
+        fields: list[str],
+        query: str = "*:*",
+        mincount: Optional[int] = None,
+        rows: Optional[int] = None,
+        filters: Optional[list[str]] = None,
+    ) -> dict[str, dict[str, int]]:
+        """Perform field faceting across one or more indexes.
+
+        Args:
+            indexes: Comma-separated index names.
+            fields: List of fields to facet on.
+            query: Lucene query to filter documents.
+            mincount: Minimum count for a value to be returned.
+            rows: Maximum number of facet values per field.
+            filters: Additional filter queries.
+
+        Returns:
+            Dictionary mapping each field to its value counts.
+        """
+        body: dict[str, Any] = {"query": query, "fields": fields}
+
+        if mincount is not None:
+            body["mincount"] = mincount
+        if rows is not None:
+            body["rows"] = rows
+        if filters:
+            body["filters"] = filters
+
+        return self._connection.post(api_path_v2("search", "facet", indexes), json=body)

{howler_client-2.4.0.dev242 → howler_client-2.4.0.dev286}/pyproject.toml

@@ -91,7 +91,7 @@ suppress-none-returning = true
 [tool.poetry]
 package-mode = true
 name = "howler-client"
-version = "2.4.0.dev242"
+version = "2.4.0.dev286"
 description = "The Howler client library facilitates issuing requests to Howler"
 authors = [
     "Canadian Centre for Cyber Security <howler@cyber.gc.ca>",

howler_client-2.4.0.dev242/howler_client/module/bundle.py

@@ -1,132 +0,0 @@
-import sys
-from typing import TYPE_CHECKING, Any
-
-from howler_client.common.utils import api_path
-from howler_client.logger import get_logger
-from howler_client.module.hit import Hit
-
-if sys.version_info >= (3, 11):
-    from typing import Self
-else:
-    from typing_extensions import Self
-
-if TYPE_CHECKING:
-    from howler_client import Connection
-
-logger = get_logger("bundle")
-
-
-class Bundle(object):
-    """Methods related to hit bundles"""
-
-    def __init__(self: Self, connection: "Connection", hit: Hit):
-        self._connection: Connection = connection
-        self._hit: Hit = hit
-
-    def __call__(self: Self, hit_id: str) -> dict[str, Any]:
-        """Return the bundle for a given ID.
-
-        Args:
-            hit_id (str): ID of the bundle
-
-        Raises:
-            ClientError: The hit does not exist
-            AttributeError: The hit is not a bundle
-
-        Returns:
-            Hit: The bundle in question
-        """
-        result = self._hit(hit_id)
-
-        if result["howler"]["is_bundle"]:
-            return result
-        else:
-            raise AttributeError("This hit is not a bundle! Use client.hit(...) instead.")
-
-    def create_from_map(
-        self: Self,
-        tool_name: str,
-        bundle_hit: dict[str, Any],
-        map: dict[str, list[str]],
-        documents: list[dict[str, Any]],
-        ignore_extra_values: bool = False,
-    ) -> list[dict[str, str | list[str] | None]]:
-        """Create a bundle using a format similar to the hit.create_from_map function
-
-        Args:
-            tool_name (str): Name of the tool the hits will be created for.
-            bundle_hit (Hit): The bundle hit
-            map (dict[str, list[str]]): Dictionary where the keys are the flattened path of the tool's raw document and
-                    the values are a list of flattened path for Howler's fields where the data will be copied into.
-            documents (list[Hit]): A list of hits to create as children of the bundle hit provided
-            ignore_extra_values (bool, optional): Ignore invalid values and return a warning, or throw an error.
-                    Defaults to False.
-
-        Returns:
-            list[dict[str, str | None]]: The list of IDs of the created hits
-        """
-        map = {**map, "bundle": ["howler.is_bundle"]}
-        bundle_hit = {**bundle_hit, "bundle": True}
-        hit = [bundle_hit] + documents
-
-        return self._hit.create_from_map(tool_name, map, hit, ignore_extra_values=ignore_extra_values)
-
-    def create(
-        self: Self,
-        bundle_hit: dict[str, Any],
-        data: dict[str, Any] | list[dict[str, Any]] | None = None,
-        ignore_extra_values: bool = False,
-    ) -> dict[str, Any] | None:
-        """Create a bundle using a format similar to the hit.create function
-
-        Args:
-            bundle_hit (dict[str, Any]): The bundle hit to create
-            data (Union[dict[str, Any], list[dict[str, Any]]], optional): A Hit or list of Hits to create as
-                    children of the bundle hit
-            ignore_extra_values (bool, optional): Ignore invalid values and return a warning, or throw an error.
-                    Defaults to False.
-
-        Returns:
-            Hit: The created bundle hit
-        """
-        if not data:
-            data = []
-
-        if not isinstance(data, list):
-            data = [data]
-
-        if len(data) > 0:
-            result = self._hit.create(data, ignore_extra_values=ignore_extra_values)
-
-            if not result or len(result["invalid"]) > 0:
-                return result
-
-            hit_ids = [h["howler"]["id"] for h in result["valid"]]
-        else:
-            hit_ids = []
-
-        return self._connection.post(api_path("hit/bundle"), json={"bundle": bundle_hit, "hits": hit_ids})
-
-    def add(self: Self, bundle_id: str, hit_ids: str | list[str]):
-        """Add a list of hits to a bundle by their IDs
-
-        Args:
-            bundle_id (str): The ID of the bundle we want to add the hits to
-            hit_ids (str | list[str]): The list of hit IDs to add to the bundle
-        """
-        if not isinstance(hit_ids, list):
-            hit_ids = [hit_ids]
-
-        return self._connection.put(api_path("hit/bundle", bundle_id), json=hit_ids)
-
-    def remove(self: Self, bundle_id: str, hit_ids: str | list[str]):
-        """Remove a list of hits from a bundle by their IDs
-
-        Args:
-            bundle_id (str): The bundle ID from which to remove the hits
-            hit_ids (str | list[str]): A list of hit IDs to remove from the bundle
-        """
-        if not isinstance(hit_ids, list):
-            hit_ids = [hit_ids]
-
-        return self._connection.delete(api_path("hit/bundle", bundle_id), json=hit_ids)