howler-api 2.13.0.dev341__py3-none-any.whl → 2.13.0.dev342__py3-none-any.whl

howler/api/v1/search.py

@@ -1,6 +1,9 @@
+import re
+from copy import deepcopy
 from typing import Any, Union
 
 from elasticsearch import BadRequestError
+from elasticsearch._sync.client.indices import IndicesClient
 from flask import request
 from sigma.backends.elasticsearch import LuceneBackend
 from sigma.rule import SigmaRule
@@ -14,7 +17,7 @@ from howler.common.swagger import generate_swagger_docs
 from howler.datastore.exceptions import SearchException
 from howler.helper.search import get_collection, get_default_sort, has_access_control, list_all_fields
 from howler.security import api_login
-from howler.services import hit_service
+from howler.services import hit_service, lucene_service
 
 SUB_API = "search"
 search_api = make_subapi_blueprint(SUB_API, api_version=1)
@@ -146,6 +149,76 @@ def search(index, **kwargs):
         return bad_request(err=f"SearchException: {e}")
 
 
+@generate_swagger_docs()
+@search_api.route("/<index>/explain", methods=["GET", "POST"])
+@api_login(required_priv=["R"])
+def explain_query(index, **kwargs):
+    """Search through specified index for a given Lucene query. Uses Lucene search syntax for query.
+
+    Variables:
+    index  =>   Index to explain against (hit, user,...)
+
+    Arguments:
+    query   =>   Lucene Query to explain
+
+    Data Block:
+    # Note that the data block is for POST requests only!
+    {
+        "query": "id:*", # Lucene Query to explain
+    }
+
+
+    Result Example:
+    {
+        'valid': True,
+        'explanations': [
+            {
+                'valid': True,
+                'explanation': 'ConstantScore(FieldExistsQuery [field=id])'
+            }
+        ]
+    }
+    """
+    user = kwargs["user"]
+    collection = get_collection(index, user)
+
+    if collection is None:
+        return bad_request(err=f"Not a valid index to explain: {index}")
+
+    fields = ["query"]
+    multi_fields: list[str] = []
+
+    params, req_data = generate_params(request, fields, multi_fields)
+
+    params["as_obj"] = False
+
+    query = req_data.get("query", None)
+    if not query:
+        return bad_request(err="There was no query.")
+
+    # This regex checks for lucene phrases (i.e. the "Example Analytic" part of howler.analytic:"Example Analytic")
+    # And then escapes them.
+    # https://regex101.com/r/8u5F6a/1
+    escaped_lucene = re.sub(r'((:\()?(".+?")(\)?))', lucene_service.replace_lucene_phrase, query)
+
+    try:
+        indices_client = IndicesClient(datastore().hit.datastore.client)
+
+        result = deepcopy(
+            indices_client.validate_query(q=escaped_lucene, explain=True, index=collection().index_name).body
+        )
+
+        del result["_shards"]
+
+        for explanation in result["explanations"]:
+            del explanation["index"]
+
+        return ok(result)
+    except Exception as e:
+        logger.exception("Exception on query explanation")
+        return bad_request(err=f"Exception: {e}")
+
+
 @generate_swagger_docs()
 @search_api.route("/<index>/eql", methods=["GET", "POST"])
 @api_login(required_priv=["R"])

{howler_api-2.13.0.dev341.dist-info → howler_api-2.13.0.dev342.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-api
-Version: 2.13.0.dev341
+Version: 2.13.0.dev342
 Summary: Howler - API server
 License: MIT
 Keywords: howler,alerting,gc,canada,cse-cst,cse,cst,cyber,cccs

{howler_api-2.13.0.dev341.dist-info → howler_api-2.13.0.dev342.dist-info}/RECORD

@@ -24,7 +24,7 @@ howler/api/v1/help.py,sha256=hqBvzW-DYX-I4Q85dbCQgpHsXyWDXp06a1fE9zhFMH4,823
 howler/api/v1/hit.py,sha256=HKaI72k7VC0v4QPjE2zcAV6jizvY2ZWEpk1BiAklvgU,34031
 howler/api/v1/notebook.py,sha256=-cahdJ9u1lAB_nheztayHKtXvoPZcj04N8nqQ2U-HLo,2015
 howler/api/v1/overview.py,sha256=e-WiHuMvOPy8Y7xIGnceagdI0_jebqlgDxi6GE6tfaA,4999
-howler/api/v1/search.py,sha256=o6jQCPnlmEhTF3lgtsDo4J_g0JQorJxxliNKZWG4wXo,24257
+howler/api/v1/search.py,sha256=24r1vaYaxDhddzDR-c5dBdRKyag6aIggvHSWPWudqN8,26372
 howler/api/v1/template.py,sha256=oexzUpAMVdgI6IOXITPx0iEfZIVP-kvlExRdFd6QVdk,5769
 howler/api/v1/tool.py,sha256=6CN5LIXgxaAvxEHE6s4IFtAEhQo_zBLtl6ghbM8whjE,6737
 howler/api/v1/user.py,sha256=YQh6eCAi4bsC_w9eGX0ZgnLoFL4z4efEc1knJsZhj4k,13842
@@ -194,7 +194,7 @@ howler/utils/path.py,sha256=DfOU4i4zSs4wchHoE8iE7aWVLkTxiC_JRGepF2hBYBk,690
 howler/utils/socket_utils.py,sha256=nz1SklC9xBHUSfHyTJjpq3mbozX1GDf01WzdGxfaUII,2212
 howler/utils/str_utils.py,sha256=HE8Hqh2HlOLaj16w0H9zKOyDJLp-f1LQ50y_WeGZaEk,8389
 howler/utils/uid.py,sha256=p9dsqyvZ-lpiAuzZWCPCeEM99kdk0Ly9czf04HNdSuw,1341
-howler_api-2.13.0.dev341.dist-info/METADATA,sha256=cux4ZHkfTdsGSV37O9Me-4EB98FVXSCF3_SXsMGMdVA,2805
-howler_api-2.13.0.dev341.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-howler_api-2.13.0.dev341.dist-info/entry_points.txt,sha256=Lu9SBGvwe0wczJHmc-RudC24lmQk7tv3ZBXon9RIihg,259
-howler_api-2.13.0.dev341.dist-info/RECORD,,
+howler_api-2.13.0.dev342.dist-info/METADATA,sha256=k-G9s9TnSg4YhLHLrWrci6m16oU21RbtaJ1kwD_F-3M,2805
+howler_api-2.13.0.dev342.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+howler_api-2.13.0.dev342.dist-info/entry_points.txt,sha256=Lu9SBGvwe0wczJHmc-RudC24lmQk7tv3ZBXon9RIihg,259
+howler_api-2.13.0.dev342.dist-info/RECORD,,