howler-api 4.0.0.dev1246__tar.gz → 4.0.0.dev1258__tar.gz

{howler_api-4.0.0.dev1246 → howler_api-4.0.0.dev1258}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-api
-Version: 4.0.0.dev1246
+Version: 4.0.0.dev1258
 Summary: Howler - API server
 License: MIT
 Keywords: howler,alerting,gc,canada,cse-cst,cse,cst,cyber,cccs
@@ -29,7 +29,7 @@ Requires-Dist: elasticsearch (==8.19.3)
 Requires-Dist: flasgger (>=0.9.7.1,<0.10.0.0)
 Requires-Dist: flask (==3.1.3)
 Requires-Dist: flask-caching (==2.4.0)
-Requires-Dist: gevent (==23.9.1)
+Requires-Dist: gevent (>=25.9.1,<26.0.0)
 Requires-Dist: gunicorn (==23.0.0)
 Requires-Dist: luqum (>=1.0.0,<2.0.0)
 Requires-Dist: mergedeep (>=1.3.4,<2.0.0)

howler_api-4.0.0.dev1258/howler/actions/add_to_bundle.py

@@ -0,0 +1,152 @@
+"""Deprecated add_to_bundle action — delegates to add_to_case via bundle_compat_service."""
+
+from typing import Optional
+
+from howler.actions import check_hit_limit
+from howler.common.exceptions import NotFoundException
+from howler.common.loader import datastore
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.case import CaseItemTypes
+from howler.odm.models.user import User
+from howler.services import bundle_compat_service, case_service
+from howler.utils.str_utils import sanitize_lucene_query
+
+OPERATION_ID = "add_to_bundle"
+MAX_HITS_BASIC = 10
+MAX_HITS_ADVANCED = 1000
+SKIP_CENTRAL_LIMIT = True  # This operation transforms the query, handles limit check locally
+
+
+def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):  # noqa: C901
+    """Add a set of hits matching the query to the specified bundle (deprecated — uses cases).
+
+    Args:
+        query (str): The query containing the matching hits
+        bundle_id (str): The ``howler.id`` of the bundle to add the hits to.
+    """
+    report = []
+
+    if not bundle_id:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Bundle ID",
+                "message": "Bundle ID cannot be empty.",
+            }
+        ]
+
+    try:
+        case = bundle_compat_service.find_case_for_bundle(bundle_id)
+        if case is None:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Invalid Bundle",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it has no associated case.",
+                }
+            )
+            return report
+
+        ds = datastore()
+
+        # Check hit limit against the query before searching
+        if user:
+            limit_error = check_hit_limit(query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
+            if limit_error:
+                return [limit_error]
+
+        matching_hits = ds.hit.search(query, rows=MAX_HITS_ADVANCED)["items"]
+
+        if not matching_hits:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
+                }
+            )
+            return report
+
+        folder = case_service.get_parent_from_path(case, "hits", create_if_missing=True)
+
+        added = []
+        skipped = []
+        for hit in matching_hits:
+            name = f"{hit.howler.analytic} ({hit.howler.id})"
+            try:
+                case_service.append_case_item(
+                    case,
+                    item_type=CaseItemTypes.HIT,
+                    item_name=name,
+                    item_value=hit.howler.id,
+                    item_parent=folder.id if folder else None,
+                )
+                added.append(hit.howler.id)
+            except Exception:  # pragma: no cover
+                skipped.append(hit.howler.id)
+
+        if skipped:
+            report.append(
+                {
+                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in skipped)})",
+                    "outcome": "skipped",
+                    "title": "Skipped Hits",
+                    "message": "These hits could not be added (already present or invalid).",
+                }
+            )
+
+        if added:
+            report.append(
+                {
+                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in added)})",
+                    "outcome": "success",
+                    "title": "Executed Successfully",
+                    "message": "The specified bundle has had all matching hits added.",
+                }
+            )
+
+    except NotFoundException as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": str(e),
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": f"Unknown exception occurred: {str(e)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Add to Bundle (Deprecated)",
+        "priority": 6,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Add a set of hits to a bundle (deprecated — uses cases)",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic", "actionrunner_basic"],
+        "steps": [
+            {
+                "args": {"bundle_id": []},
+                "options": {},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

howler_api-4.0.0.dev1258/howler/actions/add_to_case.py

@@ -0,0 +1,141 @@
+from typing import Optional
+
+import chevron
+
+from howler.common.exceptions import InvalidDataException, NotFoundException
+from howler.common.loader import datastore
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.services import case_service
+
+OPERATION_ID = "add_to_case"
+
+
+def execute(  # noqa: C901
+    query: str,
+    case_id: Optional[str] = None,
+    path: str = "related",
+    title_template: str = "{{howler.analytic}} ({{howler.id}})",
+    **kwargs,
+):
+    """Add matching alerts to a given case.
+
+    Args:
+        query (str): The query on which to apply this automation.
+        case_id (str): The ID of the case to add the alerts to.
+        path (str): The path within the case at which to place the alerts. Defaults to "related".
+        title_template (str): A Mustache-compatible template string used to generate each item's
+            name. The hit's fields are available as template variables.
+            Defaults to "{{howler.analytic}} ({{howler.id}})".
+    """
+    if not case_id:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Missing Case ID",
+                "message": "A case_id must be provided.",
+            }
+        ]
+
+    ds = datastore()
+
+    case = ds.case.get(case_id)
+    if case is None:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Case Not Found",
+                "message": f"No case with ID '{case_id}' exists.",
+            }
+        ]
+
+    hits = ds.hit.search(query, rows=1000)["items"]
+
+    if not hits:
+        return [
+            {
+                "query": query,
+                "outcome": "skipped",
+                "title": "No Matching Hits",
+                "message": "No hits matched the query, so the action was skipped.",
+            }
+        ]
+
+    report = []
+    skipped = []
+    added = []
+
+    for hit in hits:
+        title = chevron.render(title_template, hit.as_primitives())
+        item_path = f"{path.rstrip('/')}/{title}" if path else title
+        try:
+            path, name = item_path.rsplit("/", maxsplit=1)
+        except ValueError:
+            name = item_path
+
+        try:
+            parent = case_service.get_parent_from_path(case, path, create_if_missing=True)
+
+            case_service.append_case_item(
+                case,
+                item_type="hit",
+                item_value=hit.howler.id,
+                item_name=name,
+                item_parent=parent.id if parent else None,
+            )
+            added.append(hit.howler.id)
+        except InvalidDataException as e:
+            skipped.append(f"{hit.howler.id}: {e}")
+        except NotFoundException as e:  # pragma: no cover
+            skipped.append(f"{hit.howler.id}: {e}")
+        except Exception as e:  # pragma: no cover
+            skipped.append(f"{hit.howler.id}: {e}")
+
+    if added:
+        report.append(
+            {
+                "query": f"howler.id:({' OR '.join(added)})",
+                "outcome": "success",
+                "title": "Added to Case",
+                "message": f"{len(added)} alert(s) successfully added to case '{case_id}'.",
+            }
+        )
+
+    if skipped:
+        report.append(
+            {
+                "query": query,
+                "outcome": "skipped",
+                "title": "Skipped Alerts",
+                "message": f"{len(skipped)} alert(s) could not be added: {'; '.join(skipped)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Add to Case",
+        "priority": 9,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Add matching alerts to a case",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {
+                    "case_id": [],
+                    "path": [],
+                    "title_template": [],
+                },
+                "options": {},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

{howler_api-4.0.0.dev1246 → howler_api-4.0.0.dev1258}/howler/actions/demote.py

@@ -9,7 +9,7 @@ from howler.odm.models.howler_data import (
     Assessment,
     AssessmentEscalationMap,
     Escalation,
-    HitStatus,
+    Status,
 )
 from howler.odm.models.user import User
 from howler.utils.str_utils import sanitize_lucene_query
@@ -99,7 +99,7 @@ def execute(
                         "howler.assignment",
                         user.get("uname", "automation") if user else "automation",
                     ),
-                    odm_helper.update("howler.status", HitStatus.RESOLVED),
+                    odm_helper.update("howler.status", Status.RESOLVED),
                 ],
             )
 

howler_api-4.0.0.dev1258/howler/actions/remove_from_bundle.py

@@ -0,0 +1,166 @@
+"""Deprecated remove_from_bundle action — delegates to case_service for item removal."""
+
+from typing import Optional
+
+from howler.actions import check_hit_limit
+from howler.common.exceptions import NotFoundException
+from howler.common.loader import datastore
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.user import User
+from howler.services import bundle_compat_service, case_service
+from howler.utils.str_utils import sanitize_lucene_query
+
+OPERATION_ID = "remove_from_bundle"
+MAX_HITS_BASIC = 10
+MAX_HITS_ADVANCED = 1000
+SKIP_CENTRAL_LIMIT = True  # This operation transforms the query, handles limit check locally
+
+
+def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):  # noqa: C901
+    """Remove a set of hits matching the query from the specified bundle (deprecated — uses cases).
+
+    Args:
+        query (str): The query containing the matching hits
+        bundle_id (str): The ``howler.id`` of the bundle to remove the hits from.
+    """
+    report = []
+
+    if not bundle_id:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Bundle ID",
+                "message": "Bundle ID cannot be empty.",
+            }
+        ]
+
+    try:
+        case = bundle_compat_service.find_case_for_bundle(bundle_id)
+        if case is None:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Invalid Bundle",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it has no associated case.",
+                }
+            )
+            return report
+
+        ds = datastore()
+
+        # Check hit limit against the query before searching
+        if user:
+            limit_error = check_hit_limit(query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
+            if limit_error:
+                return [limit_error]
+
+        matching_hits = ds.hit.search(query, rows=MAX_HITS_ADVANCED)["items"]
+
+        if not matching_hits:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
+                }
+            )
+            return report
+
+        # Refresh case from datastore to ensure latest state
+        refreshed_case = ds.case.get(case.case_id)
+        if refreshed_case is None:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Case Not Found",
+                    "message": f"Associated case {case.case_id} no longer exists.",
+                }
+            )
+            return report
+
+        case = refreshed_case
+        case_item_values = {item.value for item in case.items}
+        values_to_remove = [h.howler.id for h in matching_hits if h.howler.id in case_item_values]
+        skipped_ids = [h.howler.id for h in matching_hits if h.howler.id not in case_item_values]
+
+        if skipped_ids:
+            report.append(
+                {
+                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in skipped_ids)})",
+                    "outcome": "skipped",
+                    "title": "Skipped Hits Not in Bundle",
+                    "message": "These hits are not in the bundle.",
+                }
+            )
+
+        if not values_to_remove:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "None of the matching hits were found in the bundle.",
+                }
+            )
+            return report
+
+        # remove_case_items expects item UUIDs (CaseItem.id), not hit value strings.
+        value_set = set(values_to_remove)
+        item_ids_to_remove = [item.id for item in case.items if item.value in value_set]
+        case_service.remove_case_items(case, item_ids_to_remove)
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Matching hits removed from bundle with id {bundle_id}",
+            }
+        )
+
+    except NotFoundException as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": str(e),
+            }
+        )
+    except Exception as e:  # pragma: no cover
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": f"Unknown exception occurred: {str(e)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Remove from Bundle (Deprecated)",
+        "priority": 5,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Remove a set of hits from a bundle (deprecated — uses cases)",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic", "actionrunner_basic"],
+        "steps": [
+            {
+                "args": {"bundle_id": []},
+                "options": {},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

{howler_api-4.0.0.dev1246 → howler_api-4.0.0.dev1258}/howler/actions/transition.py

@@ -9,12 +9,12 @@ from howler.helper.workflow import Workflow, WorkflowException
 from howler.odm.models.action import VALID_TRIGGERS
 from howler.odm.models.howler_data import (
     Assessment,
-    HitStatus,
     HitStatusTransition,
+    Status,
     Vote,
 )
 from howler.odm.models.user import User
-from howler.services import event_service, hit_service
+from howler.services import comms_service, hit_service
 from howler.utils.list_utils import flatten_list
 
 OPERATION_ID = "transition"
@@ -147,7 +147,7 @@ def execute(
         if total_processed % 10 == 0:
             log.debug("Transition executed on %s hits", total_processed)
             if request_id is not None:
-                event_service.emit(
+                comms_service.emit(
                     "automation",
                     {
                         "request_id": request_id,
@@ -193,15 +193,13 @@ def specification():
         "steps": [
             {
                 "args": {"status": []},
-                "options": {"status": HitStatus.list()},
+                "options": {"status": Status.list()},
                 "validation": {"error": {"query": "-howler.status:$status"}},
             },
             {
                 "args": {"transition": []},
                 "options": {
-                    "transition": {
-                        f"status:{status}": hit_service.get_transitions(status) for status in HitStatus.list()
-                    },
+                    "transition": {f"status:{status}": hit_service.get_transitions(status) for status in Status.list()},
                 },
             },
             {

{howler_api-4.0.0.dev1246 → howler_api-4.0.0.dev1258}/howler/api/__init__.py

@@ -25,7 +25,29 @@ logger = get_logger(__file__)
 
 def make_subapi_blueprint(name, api_version=1):
     """Create a flask Blueprint for a subapi in a standard way."""
-    return Blueprint(name, name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
+    full_name = f"v{api_version}_{name}"
+    return Blueprint(full_name, full_name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
+
+
+def _format_api_error_message(err: Exception) -> str:
+    """Format an exception for API responses using the innermost traceback frame only."""
+    trace = exc_info()[2]
+    trace_lines = format_tb(trace)
+    if trace_lines:
+        trace_lines = trace_lines[-1:]
+
+    return "".join(["\n"] + trace_lines + ["%s: %s\n" % (err.__class__.__name__, str(err))]).rstrip("\n")
+
+
+def _coerce_response_data(data: Any) -> Any:
+    """Convert ODM model responses into JSON-serializable primitives."""
+    if isinstance(data, odm.Model):
+        return data.as_primitives()
+
+    if isinstance(data, list) and len(data) > 0 and isinstance(data[0], odm.Model):
+        return [item.as_primitives() for item in data]
+
+    return data
 
 
 def _make_api_response(
@@ -43,17 +65,12 @@ def _make_api_response(
     if quota_user and quota_set and not request.path.startswith("/api/v1/clue"):
         QUOTA_TRACKER.end(quota_user)
 
-    if type(err) is Exception:  # pragma: no cover
+    if isinstance(err, Exception):  # pragma: no cover
         trace = exc_info()[2]
-        err = "".join(["\n"] + format_tb(trace) + ["%s: %s\n" % (err.__class__.__name__, str(err))]).rstrip("\n")
+        err = _format_api_error_message(err)
         log_with_traceback(trace, "Exception", is_exception=True)
 
-    if isinstance(data, odm.Model):
-        data = data.as_primitives()
-
-    if isinstance(data, list) and len(data) > 0 and isinstance(data[0], odm.Model):
-        for i in range(len(data)):
-            data[i] = data[i].as_primitives()
+    data = _coerce_response_data(data)
 
     resp = make_response(
         jsonify(