howler-api 4.0.0.dev676__tar.gz → 4.0.0.dev724__tar.gz

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-api
-Version: 4.0.0.dev676
+Version: 4.0.0.dev724
 Summary: Howler - API server
 License: MIT
 Keywords: howler,alerting,gc,canada,cse-cst,cse,cst,cyber,cccs
@@ -49,7 +49,7 @@ Requires-Dist: pytz (>=2025.2,<2026.0)
 Requires-Dist: pyyaml (==6.0.3)
 Requires-Dist: redis (==4.6.0)
 Requires-Dist: requests (==2.32.5)
-Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
+Requires-Dist: tzdata (>=2026.1,<2027.0)
 Requires-Dist: validators (>=0.34,<0.36)
 Requires-Dist: wsproto (==1.2.0)
 Project-URL: Documentation, https://cybercentrecanada.github.io/howler/developer/backend/

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/api/v1/auth.py

@@ -347,23 +347,23 @@ def login(**_):  # noqa: C901
     # For sanity's sake, we throw exceptions throughout the authentication code and simply catch the exceptions here to
     # return the corresponding HTTP Code to the user
     except (OAuthError, AuthenticationException) as err:
-        logger.warning(f"Authentication failure. (U:{user} - IP:{ip}) [{err}]")
+        logger.warning("Authentication failure. (U:%s - IP:%s) [%s]", user, ip, err)
         return unauthorized(err=str(err))
 
     except AccessDeniedException as err:
-        logger.warning(f"Authorization failure. (U:{user} - IP:{ip}) [{err}]")
+        logger.warning("Authorization failure. (U:%s - IP:%s) [%s]", user, ip, err)
         return forbidden(err=err.message)
 
     except InvalidDataException as err:
         return bad_request(err=err.message or str(err))
 
     except HowlerException:
-        logger.exception(f"Internal Authentication Error. (U:{user} - IP:{ip})")
+        logger.exception("Internal Authentication Error. (U:%s - IP:%s)", user, ip)
         return internal_error(
             err="Unhandled exception occured while Authenticating. Contact your administrator.",
         )
 
-    logger.info(f"Login successful. (U:{logged_in_uname} - IP:{ip})")
+    logger.info("Login successful. (U:%s - IP:%s)", logged_in_uname, ip)
 
     xsrf_token = generate_random_secret()
 

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/api/v1/clue.py

@@ -91,7 +91,7 @@ def proxy_to_clue(path, **kwargs):
                 timeout=5 * 60,
             )
 
-    logger.debug(f"Request to clue completed in {round(time.perf_counter() - start)}ms")
+    logger.debug("Request to clue completed in %s ms", round(time.perf_counter() - start))
 
     if not response.ok:
         return bad_gateway(response.json(), err="Something went wrong when connecting to clue")

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/api/v1/hit.py

@@ -99,7 +99,7 @@ def create_hits(user: User, **kwargs):
     response_body: dict[str, list[Any]] = {"valid": [], "invalid": []}
     odms = []
     ignore_extra_values: bool = bool(request.args.get("ignore_extra_values", False, type=lambda v: v.lower() == "true"))
-    logger.debug(f"ignore_extra_values = {ignore_extra_values}")
+    logger.debug("ignore_extra_values = %s", ignore_extra_values)
     warnings = []
     for hit in hits:
         try:
@@ -108,7 +108,7 @@ def create_hits(user: User, **kwargs):
             odms.append(odm)
             warnings.extend(_warnings)
         except HowlerException as e:
-            logger.warning(f"{type(e).__name__} when saving new hit!")
+            logger.warning("%s when saving new hit!", type(e).__name__)
             logger.warning(e)
             response_body["invalid"].append({"input": hit, "error": str(e)})
 

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/api/v1/tool.py

@@ -67,7 +67,7 @@ def create_one_or_many_hits(tool_name: str, user: User, **kwargs):  # noqa: C901
     field_map = data.pop("map", None)
     hits = data.pop("hits", None)
     ignore_extra_values: bool = bool(request.args.get("ignore_extra_values", False, type=lambda v: v.lower() == "true"))
-    logger.debug(f"ignore_extra_values = {ignore_extra_values}")
+    logger.debug("ignore_extra_values = %s", ignore_extra_values)
     # Check data type
     if not isinstance(field_map, dict):
         return bad_request(err="Invalid: 'map' field is missing or invalid.")
@@ -114,7 +114,7 @@ def create_one_or_many_hits(tool_name: str, user: User, **kwargs):  # noqa: C901
                     try:
                         field_data: Optional[_Field] = hit_fields[target]
                     except KeyError:
-                        logger.debug(f"`{target}` not in hit fields")
+                        logger.debug("`%s` not in hit fields", target)
                         field_data = next(
                             (v for k, v in hit_fields.items() if get_parent_key(k) == target),
                             None,
@@ -147,7 +147,7 @@ def create_one_or_many_hits(tool_name: str, user: User, **kwargs):  # noqa: C901
                 }
             )
         except HowlerException as e:
-            logger.warning(f"{type(e).__name__} when saving {cur_id}!")
+            logger.warning("%s when saving %s!", type(e).__name__, cur_id)
             logger.warning(e)
 
             out.append({"id": None, "error": str(e)})

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/app.py

@@ -216,7 +216,7 @@ if logger.parent:
 
 # Setup APMs
 if config.core.metrics.apm_server.server_url is not None:
-    logger.info(f"Exporting application metrics to: {config.core.metrics.apm_server.server_url}")
+    logger.info("Exporting application metrics to: %s", config.core.metrics.apm_server.server_url)
     ElasticAPM(
         app,
         server_url=config.core.metrics.apm_server.server_url,

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/common/loader.py

@@ -60,9 +60,9 @@ def get_classification(yml_config: Optional[str] = None):  # noqa: C901
                 )
 
         if not yml_config_path.exists():
-            log.warning(f"{yml_config_path} does not exist!")
+            log.warning("%s does not exist!", yml_config_path)
             yml_config_path = Path("/etc") / APP_NAME.replace("-dev", "") / "classification.yml"
-            log.warning(f"Checking at {yml_config_path} instead.")
+            log.warning("Checking at %s instead.", yml_config_path)
     else:
         yml_config_path = Path(yml_config)
 

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/cronjobs/retention.py

@@ -39,7 +39,7 @@ def setup_job(sched: BaseScheduler):
 
         return
 
-    logger.debug(f"Initializing retention cronjob with cron {config.system.retention.crontab}")
+    logger.debug("Initializing retention cronjob with cron %s", config.system.retention.crontab)
 
     if DEBUG:
         _kwargs: dict[str, Any] = {"next_run_time": datetime.now()}

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/cronjobs/view_cleanup.py

@@ -68,7 +68,7 @@ def setup_job(sched: BaseScheduler):
 
         return
 
-    logger.debug(f"Initializing view cleanup cronjob with cron {config.system.view_cleanup.crontab}")
+    logger.debug("Initializing view cleanup cronjob with cron %s", config.system.view_cleanup.crontab)
 
     if DEBUG:
         _kwargs: dict[str, Any] = {"next_run_time": datetime.now()}

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/datastore/collection.py

@@ -398,7 +398,7 @@ class ESCollection(Generic[ModelType]):
             except elasticsearch.exceptions.TransportError as e:
                 err_code, msg, cause = e.args
                 if err_code == 503 or err_code == "503":
-                    logger.warning(f"Looks like index {self.name} is not ready yet, retrying...")
+                    logger.warning("Looks like index %s is not ready yet, retrying...", self.name)
                     time.sleep(min(retries, self.MAX_RETRY_BACKOFF))
                     self.datastore.connection_reset()
                     retries += 1
@@ -411,7 +411,8 @@ class ESCollection(Generic[ModelType]):
                     retries += 1
                 elif err_code == 403 or err_code == "403":
                     logger.warning(
-                        f"Elasticsearch cluster is preventing writing operations on index {self.name}, retrying..."
+                        "Elasticsearch cluster is preventing writing operations on index %s, retrying...",
+                        self.name,
                     )
                     time.sleep(min(retries, self.MAX_RETRY_BACKOFF))
                     self.datastore.connection_reset()
@@ -470,7 +471,7 @@ class ESCollection(Generic[ModelType]):
             except elasticsearch.exceptions.TransportError as e:
                 err_code, _, _ = e.args
                 if err_code == 408 or err_code == "408":
-                    logger.warning(f"Waiting for index {index} to get to status {min_status}...")
+                    logger.warning("Waiting for index %s to get to status %s...", index, min_status)
                 else:
                     raise
 
@@ -576,8 +577,9 @@ class ESCollection(Generic[ModelType]):
 
         if cur_shards > target_shards:
             logger.info(
-                f"Current shards ({cur_shards}) is bigger then target shards ({target_shards}), "
-                "we will be shrinking the index."
+                "Current shards (%s) is bigger then target shards (%s), we will be shrinking the index.",
+                cur_shards,
+                target_shards,
             )
             if cur_shards % target_shards != 0:
                 logger.info("The target shards is not a factor of the current shards, aborting...")
@@ -591,8 +593,9 @@ class ESCollection(Generic[ModelType]):
                 method = self.datastore.client.indices.shrink
         elif cur_shards < target_shards:
             logger.info(
-                f"Current shards ({cur_shards}) is smaller then target shards ({target_shards}), "
-                "we will be splitting the index."
+                "Current shards (%s) is smaller then target shards (%s), we will be splitting the index.",
+                cur_shards,
+                target_shards,
             )
             if target_shards % cur_shards != 0:
                 logger.warning("The current shards is not a factor of the target shards, aborting...")
@@ -601,13 +604,15 @@ class ESCollection(Generic[ModelType]):
                 method = self.datastore.client.indices.split
         else:
             logger.info(
-                f"Current shards ({cur_shards}) is equal to the target shards ({target_shards}), "
-                "only house keeping operations will be performed."
+                "Current shards (%s) is equal to the target shards (%s), only housekeeping operations will be "
+                "performed.",
+                cur_shards,
+                target_shards,
             )
 
         if method:
             # Before we do anything, we should make sure the source index is in a good state
-            logger.info(f"Waiting for {self.name.upper()} status to be GREEN.")
+            logger.info("Waiting for %s status to be GREEN.", self.name.upper())
             self._wait_for_status(self.name, min_status="green")
 
             # Block all indexes to be written to
@@ -618,7 +623,7 @@ class ESCollection(Generic[ModelType]):
             if not self.with_retries(self.datastore.client.indices.exists, index=temp_name):
                 # if there are specific settings to be applied to the index, apply them
                 if clone_setup_settings:
-                    logger.info(f"Rellocating index to node {target_node.upper()}.")
+                    logger.info("Relocating index to node %s.", target_node.upper())
                     self.with_retries(
                         self.datastore.client.indices.put_settings,
                         index=self.index_name,
@@ -630,7 +635,7 @@ class ESCollection(Generic[ModelType]):
                         time.sleep(1)
 
                 # Make a clone of the current index
-                logger.info(f"Cloning {self.index_name.upper()} into {temp_name.upper()}.")
+                logger.info("Cloning %s into %s.", self.index_name.upper(), temp_name.upper())
                 self._safe_index_copy(
                     self.datastore.client.indices.clone,
                     self.index_name,
@@ -640,14 +645,16 @@ class ESCollection(Generic[ModelType]):
                 )
 
             # Make 100% sure temporary index is ready
-            logger.info(f"Waiting for {temp_name.upper()} status to be GREEN.")
+            logger.info("Waiting for %s status to be GREEN.", temp_name.upper())
             self._wait_for_status(temp_name, "green")
 
             # Make sure temporary index is the alias if not already
             if self._get_current_alias(self.name) != temp_name:
                 logger.info(
-                    f"Make {temp_name.upper()} the current alias for {self.name.upper()} "
-                    f"and delete {self.index_name.upper()}."
+                    "Make %s the current alias for %s and delete %s.",
+                    temp_name.upper(),
+                    self.name.upper(),
+                    self.index_name.upper(),
                 )
                 # Make the hot index the temporary index while deleting the original index
                 alias_actions = [
@@ -658,17 +665,19 @@ class ESCollection(Generic[ModelType]):
 
             # Make sure the original index is deleted
             if self.with_retries(self.datastore.client.indices.exists, index=self.index_name):
-                logger.info(f"Delete extra {self.index_name.upper()} index.")
+                logger.info("Delete extra %s index.", self.index_name.upper())
                 self.with_retries(self.datastore.client.indices.delete, index=self.index_name)
 
             # Shrink/split the temporary index into the original index
-            logger.info(f"Perform shard fix operation from {temp_name.upper()} to {self.index_name.upper()}.")
+            logger.info("Perform shard fix operation from %s to %s.", temp_name.upper(), self.index_name.upper())
             self._safe_index_copy(method, temp_name, self.index_name, settings=settings)
 
             # Make the original index the new alias
             logger.info(
-                f"Make {self.index_name.upper()} the current alias for {self.name.upper()} "
-                f"and delete {temp_name.upper()}."
+                "Make %s the current alias for %s and delete %s.",
+                self.index_name.upper(),
+                self.name.upper(),
+                temp_name.upper(),
             )
             alias_actions = [
                 {"add": {"index": self.index_name, "alias": self.name}},
@@ -681,7 +690,7 @@ class ESCollection(Generic[ModelType]):
         self.with_retries(self.datastore.client.indices.put_settings, settings=write_unblock_settings)
 
         # Restore normal routing and replicas
-        logger.debug(f"Restore original routing table for {self.name.upper()}.")
+        logger.debug("Restore original routing table for %s.", self.name.upper())
         self.with_retries(
             self.datastore.client.indices.put_settings,
             index=self.name,
@@ -849,7 +858,7 @@ class ESCollection(Generic[ModelType]):
                     key_list.remove(row["_id"])
                     add_to_output(row["_source"], row["_id"])
                 except ValueError:
-                    logger.exception(f"MGet returned multiple documents for id: {row['_id']}")
+                    logger.exception("MGet returned multiple documents for id: %s", row["_id"])
 
         if key_list and error_on_missing:
             raise MultiKeyError(key_list, out)
@@ -2358,7 +2367,7 @@ class ESCollection(Generic[ModelType]):
         """
         # Create HOT index
         if not self.with_retries(self.datastore.client.indices.exists, index=self.name):
-            logger.debug(f"Index {self.name.upper()} does not exists. Creating it now...")
+            logger.debug("Index %s does not exist. Creating it now...", self.name.upper())
             try:
                 self.with_retries(
                     self.datastore.client.indices.create,
@@ -2369,7 +2378,7 @@ class ESCollection(Generic[ModelType]):
             except elasticsearch.exceptions.RequestError as e:
                 if "resource_already_exists_exception" not in str(e):
                     raise
-                logger.warning(f"Tried to create an index template that already exists: {self.name.upper()}")
+                logger.warning("Tried to create an index template that already exists: %s", self.name.upper())
 
             self.with_retries(
                 self.datastore.client.indices.put_alias,

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/datastore/migrations/fix_process.py

@@ -15,12 +15,12 @@ def migrate():
         logger.info("Preconditions met, continuing.")
 
         db_size = collection.search("howler.id:*", track_total_hits=True, rows=0)["total"]
-        logger.info(f"Database size pre-migration: {db_size}")
+        logger.info("Database size pre-migration: %s", db_size)
     else:
         logger.info("Preconditions not met, stopping")
         return
 
-    logger.info(f"We will delete {result['total']} hits. Continue?")
+    logger.info("We will delete %s hits. Continue?", result["total"])
     prompt_result = input("y/[n]")
 
     if prompt_result.lower() != "y":
@@ -32,7 +32,7 @@ def migrate():
     collection.commit()
 
     db_size_after = collection.search("howler.id:*", track_total_hits=True, rows=0)["total"]
-    logger.info(f"Database size post-migration: {db_size_after}")
+    logger.info("Database size post-migration: %s", db_size_after)
 
     logger.info("Migration complete")
 

howler_api-4.0.0.dev724/howler/external/README.md

@@ -0,0 +1,30 @@
+# External scripts
+
+## reindex_data.py
+
+Reindex one or more Elasticsearch indexes used by Howler.
+
+### Usage
+
+```bash
+# Reindex specific indexes (confirms each one before proceeding)
+python reindex_data.py hit user
+
+# Reindex all indexes
+python reindex_data.py --all
+
+# Skip confirmation prompts and countdown
+python reindex_data.py hit --force
+
+# Print index schema before reindexing
+python reindex_data.py hit --verbose
+```
+
+### Options
+
+| Argument    | Description                                  |
+|-------------|----------------------------------------------|
+| `indexes`   | One or more index names to reindex.          |
+| `--all`     | Reindex all indexes.                         |
+| `--force`   | Skip confirmation prompts and countdown.     |
+| `--verbose` | Print the index schema before reindexing.    |

howler_api-4.0.0.dev724/howler/external/reindex_data.py

@@ -0,0 +1,64 @@
+import argparse
+import json
+import time
+
+DELAY = 5
+INDEX_NAMES = ["analytic", "hit", "view", "template", "overview", "action", "user", "dossier"]
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Reindex elasticsearch indexes.",
+        epilog=f"Valid index names: {', '.join(INDEX_NAMES)}",
+    )
+    parser.add_argument("indexes", nargs="*", help="Indexes to reindex.")
+    parser.add_argument("--all", action="store_true", help="Reindex all indexes.")
+    parser.add_argument("--force", action="store_true", help="Skip confirmation prompts and countdown.")
+    parser.add_argument("--verbose", action="store_true", help="Print index schema before reindexing.")
+    args = parser.parse_args()
+
+    if args.all and args.indexes:
+        parser.error("--all cannot be combined with positional index arguments.")
+
+    if not args.indexes and not args.all:
+        parser.error("Provide index names as arguments, or use --all.")
+
+    invalid = [name for name in args.indexes if name not in INDEX_NAMES]
+    if invalid:
+        parser.error(f"Invalid index(es): {', '.join(invalid)}. Valid options: {', '.join(INDEX_NAMES)}")
+
+    from howler.datastore.collection import ESCollection
+
+    ESCollection.IGNORE_ENSURE_COLLECTION = True
+
+    if args.force:
+        ESCollection.ENSURE_COLLECTION_WARNED = True
+
+    from howler.common import loader
+
+    ds = loader.datastore(archive_access=False)
+
+    selected = list(dict.fromkeys(INDEX_NAMES if args.all else args.indexes))
+
+    for index_name in selected:
+        collection: ESCollection = getattr(ds, index_name)
+
+        if args.verbose:
+            print(f"Index schema for '{index_name}':")
+            print(json.dumps(collection._get_index_mappings(), indent=2))
+
+        print(f"Reindexing: {', '.join(collection.index_list_full)}")
+
+        if not args.force:
+            answer = input(f"Are you sure you want to reindex '{index_name}'? [yes/NO] ")
+            if not answer.startswith("y"):
+                print("Confirmation not provided, skipping.")
+                continue
+
+            for i in range(2 * DELAY):
+                print(f"Reindexing in {2 * DELAY - i}...", end="\r")
+                time.sleep(1)
+            print()
+
+        result = collection.reindex()
+        print(f"Reindex of '{index_name}' complete. Success: {result}.")

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/helper/discover.py

@@ -51,11 +51,11 @@ def get_apps_list(discovery_url: Optional[str]) -> list[dict[str, str]]:
                             )
 
                     except Exception:
-                        logger.exception(f"Failed to parse get app: {str(app)}")
+                        logger.exception("Failed to parse get app: %s", str(app))
             else:
-                logger.warning(f"Invalid response from server for apps discovery: {discovery_url}")
+                logger.warning("Invalid response from server for apps discovery: %s", discovery_url)
         except Exception:
-            logger.exception(f"Failed to get apps from discover URL: {discovery_url}")
+            logger.exception("Failed to get apps from discover URL: %s", discovery_url)
 
         DISCO_CACHE[discovery_url] = sorted(apps, key=lambda k: k["name"])
         return sorted(apps, key=lambda k: k["name"])

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/odm/base.py

@@ -1503,11 +1503,31 @@ def recursive_set_name(field, name, to_parent=False):
         recursive_set_name(field.child_type, name, to_parent=True)
 
 
-def model(index=None, store=None, description=None):
-    """Decorator to create model objects."""
+def model(index=None, store=None, description=None, id_field=None):
+    """Decorator that finalizes a Model subclass for use with the datastore.
+    Assigns metadata to the class (description, id field), validates that all
+    declared field names are legal, recursively sets each field's name, and
+    applies default index/store settings to every field.
+    If ``id_field`` is not provided, it defaults to ``<classname_lower>_id``.
+    Args:
+        index: Default index setting applied to all fields on the model.
+        store: Default store setting applied to all fields on the model.
+        description: Human-readable description of the model.
+        id_field: Name of the field used as the primary key. Defaults to
+            ``<classname_lower>_id`` when not specified.
+    Returns:
+        A class decorator that configures and returns the decorated Model subclass.
+    Raises:
+        HowlerValueError: If any field name fails the ``FIELD_SANITIZER`` regex
+            or appears in ``BANNED_FIELDS``.
+    """
 
     def _finish_model(cls):
         cls._Model__description = description
+        cls._Model__id_field = id_field
+
+        if cls._Model__id_field is None:
+            cls._Model__id_field = f"{cls.__name__.lower()}_id"
 
         for name, field_data in cls.fields().items():
             if not FIELD_SANITIZER.match(name) or name in BANNED_FIELDS:

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/odm/helper.py

@@ -471,7 +471,7 @@ def create_users_with_username(ds: HowlerDatastore, usernames: list[str]):
         ds.user.save(username, user_data)
 
         if "pytest" not in sys.modules:
-            logger.info(f"{username}:{username}")
+            logger.info("%s:%s", username, username)
 
     ds.user.commit()
     ds.user_avatar.commit()

howler_api-4.0.0.dev724/howler/odm/mixins.py

@@ -0,0 +1,97 @@
+"""Datastore convenience mixins for Howler ODM Model classes.
+
+Provides :class:`DatastoreMixin`, a generic mixin that adds a class-level
+``store`` property (returning a typed :class:`ESCollection`) and instance-level
+``ds`` / ``save`` helpers so that Model subclasses can interact with the
+Elasticsearch datastore without boilerplate.
+"""
+
+from __future__ import annotations
+
+from operator import attrgetter
+from typing import Generic, TypeVar, overload
+
+from howler.common.exceptions import HowlerRuntimeError
+from howler.common.loader import datastore
+from howler.datastore.collection import ESCollection
+from howler.odm.base import Model
+
+ModelType = TypeVar("ModelType", bound=Model)
+
+
+class _ObjectsDescriptor(Generic[ModelType]):
+    """Descriptor that provides class-level-only access to the model's ESCollection.
+
+    Intended to be accessed exclusively via the class (e.g. ``Case.store``).
+    Raises ``AttributeError`` if accessed from an instance to enforce
+    cla  # noqa: D205
+    """
+
+    @overload
+    def __get__(self, obj: None, objtype: type[ModelType]) -> ESCollection[ModelType]: ...
+
+    @overload
+    def __get__(self, obj: ModelType, objtype: type[ModelType]) -> ESCollection[ModelType]: ...
+
+    def __get__(self, obj: ModelType | None, objtype: type[ModelType] | None = None) -> ESCollection[ModelType]:
+        """Return the ESCollection for the owner class.
+
+        Args:
+            obj: The instance the descriptor was accessed from, or ``None``
+                when accessed via the class.
+            objtype: The owner class (e.g. ``Case``, ``Hit``).
+        Returns:
+            ESCollection[ModelType]: The datastore collection for *objtype*.
+        Raises:
+            AttributeError: If accessed from an instance (*obj* is not ``None``)
+                or if *objtype* cannot be determined.
+        """
+        if obj is not None:
+            raise HowlerRuntimeError(
+                f"'{type(obj).__name__}.store' is a class-level property and cannot be accessed from an instance. "
+                f"Use '{type(obj).__name__}.store' instead."
+            )
+
+        if objtype is None:
+            raise HowlerRuntimeError("Cannot resolve owner class for 'store' descriptor.")
+
+        index_name = objtype.__name__.lower()
+        return datastore()[index_name]
+
+
+class DatastoreMixin(Generic[ModelType]):
+    """Mixin that provides convenience datastore access to Model instances.
+
+    Generic over ``ModelType`` so that the ``store`` class property returns a
+    correctly-typed ``ESCollection[ModelType]``.  Adds a ``ds`` property for
+    retrieving the shared datastore connection, a ``store`` class-only property
+    for retrieving the model's ESCollection (raises ``AttributeError`` if accessed
+    from an instance), and a ``save`` method that persists the current model
+    instance using its class name as the index and its configured ID field as the
+    document key.
+    """
+
+    store: _ObjectsDescriptor = _ObjectsDescriptor()
+
+    @property
+    def ds(self):
+        """Return the shared datastore instance.
+
+        Returns:
+            The singleton datastore connection used for all persistence operations.
+        """
+        return datastore()
+
+    def save(self) -> bool:
+        """Persist the current model instance to the datastore.
+
+        Determines the target index from the lowercase class name, extracts the
+        model's ID from the configured ID field, and saves the instance.
+        Returns:
+            bool: True if the save operation succeeded, False otherwise.
+        """
+        index_name = self.__class__.__name__.lower()
+        id_field = self.__class__._Model__id_field  # type: ignore[attr-defined]
+        current_id = attrgetter(id_field)(self)
+
+        return self.ds[index_name].save(current_id, self)

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/odm/models/case.py

@@ -3,6 +3,7 @@ from typing import Any, Optional
 from howler import odm
 from howler.common.exceptions import HowlerValueError
 from howler.odm.constants import Status
+from howler.odm.mixins import DatastoreMixin
 from howler.utils.compat import StrEnum
 
 CASE_ITEM_TYPES = {"observable", "hit", "case", "lead", "reference"}
@@ -92,7 +93,7 @@ class CaseEnrichment(odm.Model):
 
 
 @odm.model(index=True, store=True, description="Case model with path-based items, enrichments, rules, and tasks.")
-class Case(odm.Model):
+class Case(DatastoreMixin["Case"], odm.Model):
     case_id: str = odm.UUID(description="A unique identifier for this case.")
     title: str = odm.Keyword(description="Case title.")
     summary: str = odm.Text(description="Short case summary.")

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/odm/models/hit.py

@@ -2,6 +2,7 @@
 
 from howler import odm
 from howler.common.logging import get_logger
+from howler.odm.mixins import DatastoreMixin
 from howler.odm.models.howler_data import HowlerData
 from howler.odm.models.record import Record
 
@@ -12,8 +13,9 @@ logger = get_logger(__file__)
     index=True,
     store=True,
     description="Howler Outline schema which is an extended version of Elastic Common Schema (ECS)",
+    id_field="howler.id",
 )
-class Hit(Record):
+class Hit(DatastoreMixin["Hit"], Record):
     # Howler extended fields. Deviates from ECS
     howler: HowlerData = odm.Compound(
         HowlerData,

{howler_api-4.0.0.dev676 → howler_api-4.0.0.dev724}/howler/odm/models/observable.py

@@ -4,6 +4,7 @@ from howler import odm
 from howler.common.exceptions import HowlerValueError
 from howler.common.logging import get_logger
 from howler.odm.howler_enum import HowlerEnum
+from howler.odm.mixins import DatastoreMixin
 from howler.odm.models.record import Record
 
 logger = get_logger(__file__)
@@ -110,8 +111,9 @@ class ObservableData(odm.Model):
     index=True,
     store=True,
     description="Observable schema which is an extended version of Elastic Common Schema (ECS)",
+    id_field="howler.id",
 )
-class Observable(Record):
+class Observable(DatastoreMixin["Observable"], Record):
     # Howler extended fields. Deviates from ECS
     howler: ObservableData = odm.Compound(
         ObservableData,