howler-api 3.2.0.dev595__tar.gz → 3.2.0.dev599__tar.gz

{howler_api-3.2.0.dev595 → howler_api-3.2.0.dev599}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-api
-Version: 3.2.0.dev595
+Version: 3.2.0.dev599
 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.3.1)
-Requires-Dist: gevent (>=25.9.1,<26.0.0)
+Requires-Dist: gevent (==23.9.1)
 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-3.2.0.dev599/howler/actions/add_to_bundle.py

@@ -0,0 +1,159 @@
+from typing import Optional
+
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.services import hit_service
+from howler.utils.str_utils import sanitize_lucene_query
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "add_to_bundle"
+
+
+def execute(query: str, bundle_id: Optional[str] = None, **kwargs):
+    """Add a set of hits matching the query to the specified bundle.
+
+    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:
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        if not bundle_hit or not bundle_hit.howler.is_bundle:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Invalid Bundle",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it is not a bundle.",
+                }
+            )
+            return report
+
+        ds = datastore()
+
+        skipped_hits_bundles = ds.hit.search(
+            f"({query}) AND howler.is_bundle:true",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits_bundles) > 0:
+            report.append(
+                {
+                    "query": f"({query}) AND howler.is_bundle:true",
+                    "outcome": "skipped",
+                    "title": "Skipped Bundles",
+                    "message": "Bundles cannot be added to a bundle.",
+                }
+            )
+
+        skipped_hits_already_added = ds.hit.search(
+            f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits_already_added) > 0:
+            report.append(
+                {
+                    "query": f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
+                    "outcome": "skipped",
+                    "title": "Skipped Hits",
+                    "message": "These hits have already been added to the specified bundle.",
+                }
+            )
+
+        safe_query = f"({query}) AND (-howler.bundles:({sanitize_lucene_query(bundle_id)}) AND howler.is_bundle:false)"
+        matching_hits = ds.hit.search(safe_query)["items"]
+        if len(matching_hits) < 1:
+            report.append(
+                {
+                    "query": safe_query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
+                }
+            )
+            return report
+
+        ds.hit.update_by_query(
+            safe_query,
+            [hit_helper.list_add("howler.bundles", sanitize_lucene_query(bundle_id), if_missing=True)],
+        )
+
+        operations = [
+            hit_helper.list_add(
+                "howler.hits",
+                hit["howler"]["id"],
+                if_missing=True,
+            )
+            for hit in matching_hits
+        ]
+
+        operations.append(hit_helper.update("howler.bundle_size", len(operations)))
+        hit_service.update_hit(
+            bundle_id,
+            operations,
+        )
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        report.append(
+            {
+                "query": safe_query.replace("-howler.bundles", "howler.bundles"),
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": "The specified bundle has had all matching hits added.",
+            }
+        )
+    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",
+        "priority": 6,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Add a set of hits to a bundle",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"bundle_id": []},
+                "options": {},
+                "validation": {
+                    "warn": {"query": "howler.bundles:($bundle_id) OR howler.is_bundle:true"},
+                    "error": {
+                        "query": "howler.id:$bundle_id AND howler.is_bundle:false",
+                        "message": "The bundle id given must be a bundle.",
+                    },
+                },
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

{howler_api-3.2.0.dev595 → howler_api-3.2.0.dev599}/howler/actions/demote.py

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

howler_api-3.2.0.dev599/howler/actions/remove_from_bundle.py

@@ -0,0 +1,133 @@
+from typing import Optional
+
+from howler.common.exceptions import HowlerException
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.services import hit_service
+from howler.utils.str_utils import sanitize_lucene_query
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "remove_from_bundle"
+
+
+def execute(query: str, bundle_id: Optional[str] = None, **kwargs):
+    """Remove a set of hits matching the query from the specified bundle.
+
+    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:
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        if not bundle_hit or not bundle_hit.howler.is_bundle:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Invalid Bundle",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it is not a bundle.",
+                }
+            )
+            return report
+
+        ds = datastore()
+
+        skipped_hits = ds.hit.search(
+            f"({query}) AND -howler.bundles:{sanitize_lucene_query(bundle_id)}",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits) > 0:
+            report.append(
+                {
+                    "query": f"howler.id:({' OR '.join(h.howler.id for h in skipped_hits)})",
+                    "outcome": "skipped",
+                    "title": "Skipped Hit not in Bundle",
+                    "message": "These hits already are not in the bundle.",
+                }
+            )
+
+        safe_query = f"{query} AND (howler.bundles:{bundle_id})"
+
+        matching_hits = ds.hit.search(safe_query)["items"]
+        if len(matching_hits) < 1:
+            report.append(
+                {
+                    "query": safe_query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
+                }
+            )
+            return report
+
+        ds.hit.update_by_query(
+            safe_query,
+            [hit_helper.list_remove("howler.bundles", bundle_id)],
+        )
+
+        hit_service.update_hit(
+            bundle_id,
+            [hit_helper.list_remove("howler.hits", h["howler"]["id"]) for h in ds.hit.search(safe_query)["items"]],
+        )
+
+        if len(ds.hit.get(bundle_id).howler.hits) < 1:
+            hit_service.update_hit(bundle_id, [hit_helper.update("howler.is_bundle", False)])
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Matching hits removed from bundle with id {bundle_id}",
+            }
+        )
+    except HowlerException 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": "Remove from Bundle",
+        "priority": 5,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Remove a set of hits from a bundle",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"bundle_id": []},
+                "options": {},
+                "validation": {"error": {"query": "-howler.bundles:$bundle_id"}},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

{howler_api-3.2.0.dev595 → howler_api-3.2.0.dev599}/howler/actions/transition.py

@@ -8,8 +8,8 @@ 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
@@ -180,13 +180,15 @@ def specification():
         "steps": [
             {
                 "args": {"status": []},
-                "options": {"status": Status.list()},
+                "options": {"status": HitStatus.list()},
                 "validation": {"error": {"query": "-howler.status:$status"}},
             },
             {
                 "args": {"transition": []},
                 "options": {
-                    "transition": {f"status:{status}": hit_service.get_transitions(status) for status in Status.list()},
+                    "transition": {
+                        f"status:{status}": hit_service.get_transitions(status) for status in HitStatus.list()
+                    },
                 },
             },
             {

{howler_api-3.2.0.dev595 → howler_api-3.2.0.dev599}/howler/api/__init__.py

@@ -24,8 +24,7 @@ logger = get_logger(__file__)
 
 def make_subapi_blueprint(name, api_version=1):
     """Create a flask Blueprint for a subapi in a standard way."""
-    full_name = f"v{api_version}_{name}"
-    return Blueprint(full_name, full_name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
+    return Blueprint(name, name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
 
 
 def _make_api_response(

howler_api-3.2.0.dev595/howler/services/docs_service.py → howler_api-3.2.0.dev599/howler/api/v1/__init__.py

@@ -1,39 +1,47 @@
 from textwrap import dedent
 
-from flask import current_app, request
-
-
-def build_route_docs(version: str, user_types: list[str]):
-    """This function iterates through all registered Flask routes.
-
-    It generates documentation for those accessible by the specified user types. It collects
-    route metadata including permissions, methods, descriptions, and completion status.
-
-    Args:
-        user_types (list[str]): List of user types to filter API routes by.
-            Only routes that grant access to at least one of these user types
-            will be included in the output.
-
-    Returns:
-        dict: A dictionary containing:
-            - 'apis' (list[dict]): List of API endpoint documentation, each dict includes:
-                - 'protected' (bool): Whether the endpoint requires authentication.
-                - 'required_type' (list[str]): User types allowed to access this endpoint.
-                - 'name' (str): Human-readable name of the endpoint.
-                - 'id' (str): Unique identifier for the endpoint.
-                - 'function' (str): Full Python function path.
-                - 'path' (str): URL path of the endpoint.
-                - 'ui_only' (bool): Whether endpoint is UI-only.
-                - 'methods' (list[str]): HTTP methods supported (excluding OPTIONS and HEAD).
-                - 'description' (str): Docstring documentation or incomplete marker.
-                - 'complete' (bool): Whether the endpoint is fully documented.
-                - 'required_priv' (list[str]): Required privileges for the endpoint.
-            - 'blueprints' (dict[str, str]): Map of blueprint names to their documentation strings.
-
-    Note:
-        Endpoints without documentation are marked with "[INCOMPLETE]" prefix
-        in their description and complete field set to False.
+from flask import Blueprint, current_app, request
+
+from howler.api import ok
+from howler.security import api_login
+
+API_PREFIX = "/api/v1"
+apiv1 = Blueprint("apiv1", __name__, url_prefix=API_PREFIX)
+apiv1._doc = "Api Documentation Version 1"  # type: ignore[attr-defined] # type: ignore
+
+
+@apiv1.route("/")
+@api_login(audit=False, required_priv=["R", "W"], required_type=["user", "admin"])
+def get_api_documentation(**kwargs):
+    """Full API doc.
+
+    Loop through all registered API paths and display their documentation.
+    Returns a list of API definition.
+
+    Variables:
+    None
+
+    Arguments:
+    None
+
+    Result Example:
+    [
+        {
+            'name': "Api Doc",                  # Name of the api
+            'path': "/api/path/<variable>/",    # API path
+            'ui_only': false,                   # Is UI only API
+            'methods': ["GET", "POST"],         # Allowed HTTP methods
+            'description': "API doc.",          # API documentation
+            'id': "api_doc",                    # Unique ID for the API
+            'function': "apiv1.api_doc",        # Function called in the code
+            'protected': False,                 # Does the API require login?
+            'required_type': ['user'],           # Type of users allowed to use API
+            'complete' : True                   # Is the API stable?
+        },
+    ]
     """
+    user_types = kwargs["user"]["type"]
+
     api_blueprints = {}
     api_list = []
     for rule in current_app.url_map.iter_rules():
@@ -50,7 +58,7 @@ def build_route_docs(version: str, user_types: list[str]):
                         [x.capitalize() for x in rule.endpoint[rule.endpoint.rindex(".") + 1 :].split("_")]
                     )
                     blueprint = rule.endpoint[: rule.endpoint.rindex(".")]
-                    if blueprint == f"api{version}":
+                    if blueprint == "apiv1":
                         blueprint = "documentation"
 
                     if blueprint not in api_blueprints:
@@ -66,7 +74,7 @@ def build_route_docs(version: str, user_types: list[str]):
                     else:
                         description = "[INCOMPLETE]\n\nTHIS API HAS NOT BEEN DOCUMENTED YET!"
 
-                    api_id = rule.endpoint.replace(f"api{version}.", "").replace(".", "_")
+                    api_id = rule.endpoint.replace("apiv1.", "").replace(".", "_")
 
                     api_list.append(
                         {
@@ -74,7 +82,7 @@ def build_route_docs(version: str, user_types: list[str]):
                             "required_type": sorted(required_type),
                             "name": func_title,
                             "id": api_id,
-                            "function": f"api.{version}.{rule.endpoint}",
+                            "function": f"api.v1.{rule.endpoint}",
                             "path": rule.rule,
                             "ui_only": rule.rule.startswith("%sui/" % request.path),
                             "methods": sorted(methods),
@@ -86,4 +94,4 @@ def build_route_docs(version: str, user_types: list[str]):
 
                     break
 
-    return {"apis": api_list, "blueprints": api_blueprints}
+    return ok({"apis": api_list, "blueprints": api_blueprints})

{howler_api-3.2.0.dev595 → howler_api-3.2.0.dev599}/howler/api/v1/action.py

@@ -231,7 +231,8 @@ def execute_action(id: str, **kwargs) -> Response:
     if not isinstance(execute_req, dict):
         return bad_request(err="Incorrect data structure!")
 
-    action = datastore().action.get(id)
+    action: Action = datastore().action.get(id)
+
     if not action:
         return not_found(err="The specified action does not exist")