howler-api 3.0.0.dev374__py3-none-any.whl

howler/actions/example_plugin.py

@@ -0,0 +1,104 @@
+from howler.odm.models.action import VALID_TRIGGERS
+
+OPERATION_ID = "example_plugin"
+
+
+def execute(query: str, arg1: str, arg2: str, **kwargs):
+    """This function is called either when triggered manually or any of the accepted triggers are met.
+
+    Args:
+        query (str): The query this action is running on
+        arg1 (str, optional): The provided value for the matching argument below. One of "a", "b", "c".
+        arg2 (str, optional): The provided value for the matching argument below. Freeform text.
+    """
+    report = []
+
+    try:
+        # Do whatever you want here - make requests, parse them, etc.
+
+        # There are three types of responses you can add to the report - success, skipped and error.
+        if arg1 in ["a", "c"]:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "success",
+                    "title": "Executed Successfully",
+                    "message": "Example action ran successfully!",
+                }
+            )
+        else:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "skipped",
+                    "title": "Execution Skipped",
+                    "message": "Since arg1 was b, we didn't run the action.",
+                }
+            )
+    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():
+    """A function that returns information about how to present the action in the UI.
+
+    This information includes what information must be provided, and how the UI should ask for it, as well as basic
+    data validation.
+    """
+    return {
+        "id": OPERATION_ID,
+        # The string to use if no localization is available
+        "title": "Example Plugin",
+        # If you have a localization key in the UI, set it here.
+        "i18nKey": f"operations.{OPERATION_ID}",
+        # Provide a short and long description. These must be useful - they'll be presented to users in the UI.
+        "description": {
+            "short": "Just an example plugin implementation",
+            "long": execute.__doc__,
+        },
+        # What roles should be necessary to run this action? In general, automation_basic should always be required,
+        # while automation_advanced should be set when this action could be dangerous or costly in terms of resources.
+        "roles": ["automation_basic"],
+        # What data should the user be required to provide? This is split intop steps, so arguments can depend on each
+        # other, giving basic control flow for specifying arguments.
+        "steps": [
+            {
+                # A list of argument values the user must provide in this step
+                "args": {"arg1": []},
+                # Specifying a matching key corresponding to a list of strings in options will allow users to choose
+                # from a  pre-defined list of values, while not providing it will allow them to enter any freeform text.
+                "options": {"arg1": ["a", "b", "c"]},
+                # You can specify "warn" and "error" validation queries. The UI will pop up a warning or error if this
+                #  query returns a match when ANDed with the supplied query. i.e. say the query they are running the
+                # action on is "howler.id:*" and they have chosen "a" for arg1, then
+                # if the query "howler.id:* AND howler.labels.generic:*a*" has any matches, this will warn the user.
+                "validation": {
+                    "warn": {
+                        # The query to match against. Basic replacement works, i.e. $<var_name> =>
+                        # replaced with the value for var_name.
+                        "query": "howler.labels.generic:*$arg1*",
+                        # What message should be shown? This is optional - a generic message will be shown otherwise
+                        "message": "You can't have a label that contains the character chosen as arg1!",
+                    }
+                },
+            },
+            {
+                # This means that the UI for adding an input for arg2 will only be required if arg1 is "a" or "b",
+                # not "c".
+                "args": {"arg2": ["arg1:a", "arg1:b"]},
+                # No options provided => freeform text
+                "options": {},
+            },
+        ],
+        # What triggers should one be able to use this action with? In this case, we allow all of them.
+        "triggers": VALID_TRIGGERS,
+    }

howler/actions/prioritization.py

@@ -0,0 +1,93 @@
+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
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "prioritization"
+
+VALID_FIELDS = ["reliability", "severity", "volume", "confidence", "score"]
+
+
+def execute(query: str, field: str = "score", value: str = "0.0", **kwargs):
+    """Change one of the priorization fields of a hit
+
+    Args:
+        query (str): The query to run this action on
+        field (str, optional): The field to update. Defaults to "score".
+        value (str, optional): The value to set it to. Must be a float in string format. Defaults to "0.0".
+    """
+    if field not in VALID_FIELDS:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid field",
+                "message": (
+                    f"Field 'howler.{field}' does not exist. You must pick from one of the following "
+                    + f"values: {', '.join(VALID_FIELDS)}."
+                ),
+            }
+        ]
+
+    report = []
+
+    try:
+        value: float = float(value)
+
+        datastore().hit.update_by_query(
+            query,
+            [hit_helper.update(f"howler.{field}", value)],
+        )
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Field 'howler.{field}' updated to value '{value}' for all matching hits.",
+            }
+        )
+    except ValueError:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Value",
+                "message": f"'{value}' is not a valid value. It must be a float (i.e. 12.34)",
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": 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": "Change Prioritization",
+        "priority": 10,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Change one of the prioritization fields of a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"field": [], "value": []},
+                "options": {"field": VALID_FIELDS},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

howler/actions/promote.py

@@ -0,0 +1,147 @@
+from typing import Optional
+
+import howler.helper.hit as hit_helper
+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.odm.models.howler_data import (
+    Assessment,
+    AssessmentEscalationMap,
+    Escalation,
+)
+from howler.utils.str_utils import sanitize_lucene_query
+
+OPERATION_ID = "promote"
+
+ESCALATIONS = [esc for esc in Escalation.list() if esc != Escalation.MISS]
+
+odm_helper = OdmHelper(Hit)
+
+
+def execute(
+    query: str,
+    escalation: Escalation = Escalation.ALERT,
+    assessment: Optional[str] = None,
+    rationale: Optional[str] = None,
+    **kwargs,
+):
+    """Promote a hit.
+
+    Args:
+        query (str): The query on which to apply this automation.
+        escalation (str, optional): The escalation to promote to. Defaults to "alert".
+        assessment (str, optional): Required if escalation is evidence, assessment to apply.
+        rationale (str, optional): The optional rationale to apply if promoting to evidence.
+    """
+    if escalation not in ESCALATIONS:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Escalation",
+                "message": f"'{escalation}' is not a valid escalation.",
+            }
+        ]
+
+    report = []
+
+    ds = datastore()
+
+    skipped_hits = ds.hit.search(
+        f"({query}) AND howler.escalation:{sanitize_lucene_query(escalation)}",
+        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 with Escalation",
+                "message": f"These hits already have the escalation {escalation}.",
+            }
+        )
+
+    try:
+        if escalation in [Escalation.HIT, Escalation.ALERT]:
+            ds.hit.update_by_query(
+                query,
+                [
+                    *hit_helper.promote_hit(escalation=escalation),
+                    odm_helper.update("howler.assessment", None),
+                    odm_helper.update("howler.rationale", None),
+                ],
+            )
+        else:
+            if not assessment:
+                report.append(
+                    {
+                        "query": query,
+                        "outcome": "error",
+                        "title": "Missing assessment",
+                        "message": "You must provide as assessment value when promoting to evidence.",
+                    }
+                )
+                return report
+
+            ds.hit.update_by_query(query, hit_helper.assess_hit(assessment, rationale))
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Promoted to '{escalation}' for all matching hits.",
+            }
+        )
+    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": "Promote Hit",
+        "i18nKey": "operations.promote",
+        "description": {
+            "short": "Promote a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"escalation": []},
+                "options": {"escalation": ESCALATIONS},
+                "validation": {"warn": {"query": "howler.escalation:$escalation"}},
+            },
+            {
+                "args": {
+                    "assessment": ["escalation:evidence"],
+                    "rationale": ["escalation:evidence"],
+                },
+                "options": {
+                    "assessment": {
+                        "escalation:evidence": [
+                            assessment
+                            for assessment in Assessment.list()
+                            if AssessmentEscalationMap[assessment] == Escalation.EVIDENCE
+                        ],
+                        "escalation:alert": [],
+                        "escalation:hit": [],
+                    }
+                },
+            },
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

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/actions/remove_label.py

@@ -0,0 +1,111 @@
+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.odm.models.howler_data import Label
+from howler.utils.str_utils import sanitize_lucene_query
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "remove_label"
+
+CATEGORIES = list(Label.fields().keys())
+
+
+def execute(query: str, category: str = "generic", label: Optional[str] = None, **kwargs):
+    """Remove a label from a hit.
+
+    Args:
+        query (str): The query on which to apply this automation.
+        category (str, optional): The category of label from which to remove the label. Defaults to "generic".
+        label (str, optional): The label to remove. Defaults to None.
+    """
+    if category not in CATEGORIES:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Category",
+                "message": f"'{category}' is not a valid category.",
+            }
+        ]
+
+    if not label:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Label",
+                "message": "Label cannot be empty.",
+            }
+        ]
+
+    report = []
+
+    ds = datastore()
+
+    skipped_hits = ds.hit.search(
+        f"({query}) AND -howler.labels.{category}:{sanitize_lucene_query(label)}",
+        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 without Label",
+                "message": f"These hits already do not have the label {label}.",
+            }
+        )
+
+    try:
+        ds.hit.update_by_query(
+            query,
+            [hit_helper.list_remove(f"howler.labels.{category}", label)],
+        )
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Label '{label}' removed from category '{category}' for all matching hits.",
+            }
+        )
+    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": "Remove Label",
+        "priority": 7,
+        "i18nKey": "operations.remove_label",
+        "description": {
+            "short": "Remove a label from a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"category": [], "label": []},
+                "options": {"category": CATEGORIES},
+                "validation": {"warn": {"query": "-howler.labels.$category:$label"}},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }