howler-sentinel-plugin 0.2.0.dev170__py3-none-any.whl

howler_sentinel_plugin-0.2.0.dev170.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: howler-sentinel-plugin
+Version: 0.2.0.dev170
+Summary: A howler plugin for integration with Microsoft's Sentinel API
+License: MIT
+License-File: LICENSE
+Author: CCCS
+Author-email: analysis-development@cyber.gc.ca
+Requires-Python: >=3.9.17, <4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Howler Sentinel Plugin
+
+This plugin contains modules for Microsoft Sentinel integration in Howler.
+

howler_sentinel_plugin-0.2.0.dev170.dist-info/RECORD

@@ -0,0 +1,21 @@
+sentinel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sentinel/actions/azure_emit_hash.py,sha256=ES9u3iIkm18qcwVT7-f3r8K5d-haCnjSTC7cyOKxH7A,4000
+sentinel/actions/send_to_sentinel.py,sha256=wrpE-ML19CPFU7l5aVWsZpiNvdyQImelt0hFwhtmXPw,4588
+sentinel/actions/update_defender_xdr_alert.py,sha256=_AS6fL0lWgrKIfd2fgVfWXyLias1uX89bZ0RgjNsB7c,6796
+sentinel/actions/update_defender_xdr_incident.py,sha256=HjvK8yTDafYePY5LoMkYat_cFUHnFWK3tzpCfAO3JNE,6854
+sentinel/config.py,sha256=RLt65CZhD0VxygWngU6RjDkrS24h1H9OMLieV4iTf9A,1788
+sentinel/manifest.yml,sha256=Ps5qp5PjcY6MY9U8wQFt-18VDpEySI0lrj25wMlxod4,222
+sentinel/mapping/sentinel_incident.py,sha256=GkOMbFLeHgKd00H8Bc42yQylr4fvO8yq8y2bM1x7c3s,9741
+sentinel/mapping/xdr_alert.py,sha256=J-o76G6gJy2R_bZO7FBgG3Ks8QToIkr5Uy7HRHzmb6w,17994
+sentinel/mapping/xdr_alert_evidence.py,sha256=iMn9Wd5NB7Wi9l0Fl0vmJhugX8L6hAO9jYA9AtLLX2o,31429
+sentinel/odm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sentinel/odm/hit.py,sha256=XEStYFIfiEUzcNVYo2Z1s6U7j6B-IDQOhRZR6YRUJn0,867
+sentinel/odm/models/sentinel.py,sha256=XT3XdT92uoCV5vmY9dT1jmcxRyuu9vp1gE8AwZdKBIc,337
+sentinel/routes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sentinel/routes/ingest.py,sha256=XlQqOaZT-6_cBUuhe_DAdD81brKIgG1B4d3ZH8JJ0NA,10788
+sentinel/utils/tenant_utils.py,sha256=Wc7v2A8pQ69YdK9LsNCb2Vmg77kV2teHq9Sqn2EKoqc,1725
+howler_sentinel_plugin-0.2.0.dev170.dist-info/METADATA,sha256=b1us70TJd8yQBmLcYWTGBcZVeIdSoGNzqxQjTj4SqDU,822
+howler_sentinel_plugin-0.2.0.dev170.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+howler_sentinel_plugin-0.2.0.dev170.dist-info/entry_points.txt,sha256=4IJyMY0V49s3Wp659ngN_7U8g66-czeKxI-_dNAFP5g,60
+howler_sentinel_plugin-0.2.0.dev170.dist-info/licenses/LICENSE,sha256=Wg2luVnxEkP2NSn11nh1US6W_nFFbICBAVTG9iG3t5M,1091
+howler_sentinel_plugin-0.2.0.dev170.dist-info/RECORD,,

howler_sentinel_plugin-0.2.0.dev170.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

howler_sentinel_plugin-0.2.0.dev170.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+type_check=build_scripts.type_check:main
+

howler_sentinel_plugin-0.2.0.dev170.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Canadian Centre for Cyber Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sentinel/actions/azure_emit_hash.py

@@ -0,0 +1,124 @@
+import os
+from typing import Any, Optional
+
+import requests
+from howler.common.loader import datastore
+from howler.common.logging import get_logger
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from pydash import get
+
+logger = get_logger(__file__)
+
+OPERATION_ID = "azure_emit_hash"
+
+
+def execute(
+    query: str,
+    url: Optional[str] = os.environ.get("SHA256_LOGIC_APP_URL", None),
+    field: str = "file.hash.sha256",
+    **kwargs,
+) -> list[dict[str, Any]]:
+    "Emit hashes to sentinel"
+    result = datastore().hit.search(query, rows=1)
+    hits = result["items"]
+
+    if not url:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Action is not properly configured",
+                "message": "url argument cannot be empty.",
+            }
+        ]
+
+    if len(hits) < 1:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "No alert found",
+                "message": "No alerts exist in this query.",
+            }
+        ]
+
+    report = []
+    hit = hits[0]
+
+    if result["total"] > 1:
+        report.append(
+            {
+                "query": f"{query} AND -howler.id:{hit.howler.id}",
+                "outcome": "skipped",
+                "title": "Action applies to a single alert",
+                "message": "This action supports execution against a single alert at once, not bulk execution.",
+            }
+        )
+
+    for hit in hits:
+        hash_value = get(hit, field)
+        if hash_value:
+            try:
+                requests.post(
+                    url,  # noqa: F821
+                    json={
+                        "indicator": hash_value,
+                        "type": "FileSha256",
+                        "description": "Sent from Howler",
+                        "action": "alert",
+                        "severity": "high",
+                    },
+                    timeout=5.0,
+                )
+                report.append(
+                    {
+                        "query": f"howler.id:{hit.howler.id}",
+                        "outcome": "success",
+                        "title": "Webhook Triggered",
+                        "message": f"Field {field} from alert {hit.howler.id} was successfully sent to url {url}.",
+                    }
+                )
+            except Exception:
+                logger.exception("Exception on network call for alert %s", hit.howler.id)
+                report.append(
+                    {
+                        "query": f"howler.id:{hit.howler.id}",
+                        "outcome": "error",
+                        "title": "Network error on execution",
+                        "message": "Alert processing failed due to network errors.",
+                    }
+                )
+        else:
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "error",
+                    "title": "Hash does not exist on alert",
+                    "message": f"The specified alert does not have a valid sha256 hash at path {field}.",
+                }
+            )
+
+    return report
+
+
+def specification():
+    "Specify various properties of the action, such as title, descriptions, permissions and input steps."
+    return {
+        "id": OPERATION_ID,
+        "title": "Emit sha256 hash to Sentinel",
+        "priority": 28,
+        "description": {
+            "short": "Emit sha256 hash to Sentinel",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"url": [], "field": []},
+                "options": {"field": [field for field in Hit.flat_fields().keys() if field.endswith("sha256")]},
+                "validation": {"warn": {"query": "-_exists_:$field"}},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

sentinel/actions/send_to_sentinel.py

@@ -0,0 +1,141 @@
+from typing import Any
+
+import requests
+from howler.common.exceptions import HowlerRuntimeError
+from howler.common.loader import datastore
+from howler.common.logging import get_logger
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+
+from sentinel.utils.tenant_utils import get_token
+
+logger = get_logger(__file__)
+
+OPERATION_ID = "send_to_sentinel"
+
+
+def execute(query: str, **kwargs) -> list[dict[str, Any]]:
+    """Send hit to Microsoft Sentinel.
+
+    Args:
+        query (str): The query on which to apply this automation.
+    """
+    report = []
+    ds = datastore()
+
+    hits: list[Hit] = ds.hit.search(query, as_obj=True)["items"]
+    if not hits:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "No hits returned by query",
+                "message": f"No hits returned by '{query}'",
+            }
+        )
+        return report
+
+    from sentinel.config import config
+
+    for hit in hits:
+        if hit.azure and hit.azure.tenant_id:
+            tenant_id = hit.azure.tenant_id
+        elif hit.organization.id:
+            tenant_id = hit.organization.id
+        else:
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "skipped",
+                    "title": "Azure Tenant ID is missing",
+                    "message": "This alert does not have a set tenant ID.",
+                }
+            )
+            continue
+
+        try:
+            token = get_token(tenant_id, "https://monitor.azure.com/.default")
+        except HowlerRuntimeError as err:
+            logger.exception("Error on token fetching")
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "error",
+                    "title": "Invalid Credentials",
+                    "message": err.message,
+                }
+            )
+            continue
+
+        ingestor = next((ingestor for ingestor in config.ingestors if ingestor.tenant_id == tenant_id), None)
+
+        if not ingestor:
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "error",
+                    "title": "Invalid Tenant ID",
+                    "message": (
+                        f"The tenant ID ({tenant_id}) associated with this alert has not been correctly configured."
+                    ),
+                }
+            )
+            continue
+
+        uri = (
+            f"https://{ingestor.dce}.ingest.monitor.azure.com/dataCollectionRules/{ingestor.dcr}/"
+            + f"streams/{ingestor.table}?api-version=2021-11-01-preview"
+        )
+
+        payload = [
+            {
+                "TimeGenerated": hit.event.ingested.isoformat(),
+                "Title": hit.howler.analytic,
+                "RawData": {"Hit": hit.as_primitives(), "From": "Howler"},
+            }
+        ]
+        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+
+        response = requests.post(uri, headers=headers, json=payload, timeout=5.0)
+        if not response.ok:
+            logger.warning(
+                "POST request to Azure Monitor failed with status code %s. Content:\n%s",
+                response.status_code,
+                response.text,
+            )
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "error",
+                    "title": "Azure Monitor API request failed",
+                    "message": f"POST request to Azure Monitor failed with status code {response.status_code}.",
+                }
+            )
+            continue
+
+        report.append(
+            {
+                "query": f"howler.id:{hit.howler.id}",
+                "outcome": "success",
+                "title": "Alert updated in Sentinel",
+                "message": "Howler has successfully propagated changes to this alert to Sentinel.",
+            }
+        )
+
+    return report
+
+
+def specification():
+    "Send to Sentinel action specification"
+    return {
+        "id": OPERATION_ID,
+        "title": "Send hit to Microsoft Sentinel",
+        "priority": 8,
+        "description": {
+            "short": "Send hit to Microsoft Sentinel",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [{"args": {}, "options": {}, "validation": {}}],
+        "triggers": VALID_TRIGGERS,
+    }

sentinel/actions/update_defender_xdr_alert.py

@@ -0,0 +1,194 @@
+import requests
+from howler.common.exceptions import HowlerRuntimeError
+from howler.common.loader import datastore
+from howler.common.logging import get_logger
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.odm.models.howler_data import Assessment, HitStatus
+
+from sentinel.utils.tenant_utils import get_token
+
+logger = get_logger(__file__)
+
+OPERATION_ID = "update_defender_xdr_alert"
+
+properties_map = {
+    "graph": {
+        "status": {
+            HitStatus.OPEN: "new",
+            HitStatus.IN_PROGRESS: "inProgress",
+            HitStatus.ON_HOLD: "inProgress",
+            HitStatus.RESOLVED: "resolved",
+        },
+        "classification": {
+            Assessment.AMBIGUOUS: "unknown",
+            Assessment.SECURITY: "informationalExpectedActivity",
+            Assessment.DEVELOPMENT: "informationalExpectedActivity",
+            Assessment.FALSE_POSITIVE: "falsePositive",
+            Assessment.LEGITIMATE: "informationalExpectedActivity",
+            Assessment.TRIVIAL: "falsePositive",
+            Assessment.RECON: "truePositive",
+            Assessment.ATTEMPT: "truePositive",
+            Assessment.COMPROMISE: "truePositive",
+            Assessment.MITIGATED: "truePositive",
+            None: "unknown",
+        },
+        "determination": {
+            Assessment.AMBIGUOUS: "unknown",
+            Assessment.SECURITY: "securityTesting",
+            Assessment.DEVELOPMENT: "confirmedUserActivity",
+            Assessment.FALSE_POSITIVE: "other",
+            Assessment.LEGITIMATE: "lineOfBusinessApplication",
+            Assessment.TRIVIAL: "other",
+            Assessment.RECON: "multiStagedAttack",
+            Assessment.ATTEMPT: "other",
+            Assessment.COMPROMISE: "maliciousUserActivity",
+            Assessment.MITIGATED: "other",
+            None: "unknown",
+        },
+    },
+}
+
+
+def execute(query: str, **kwargs):
+    """Update Microsoft Defender XDR alert.
+
+    Args:
+        query (str): The query on which to apply this automation.
+    """
+    report = []
+    ds = datastore()
+
+    hits: list[Hit] = ds.hit.search(query, as_obj=True)["items"]
+
+    if not hits:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "No hits returned by query",
+                "message": f"No hits returned by '{query}'",
+            }
+        )
+        return report
+
+    for hit in hits:
+        if hit.azure and hit.azure.tenant_id:
+            tenant_id = hit.azure.tenant_id
+        elif hit.organization.id:
+            tenant_id = hit.organization.id
+        else:
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "skipped",
+                    "title": "Azure Tenant ID is missing",
+                    "message": "This alert does not have a set tenant ID.",
+                }
+            )
+            continue
+
+        try:
+            token = get_token(tenant_id, "https://graph.microsoft.com/.default")
+        except HowlerRuntimeError as err:
+            logger.exception("Error on token fetching")
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "error",
+                    "title": "Invalid Credentials",
+                    "message": err.message,
+                }
+            )
+            continue
+
+        # Fetch alert details
+        alert_url = f"https://graph.microsoft.com/v1.0/security/alerts_v2/{hit.rule.id}"
+        response = requests.get(alert_url, headers={"Authorization": f"Bearer {token}"}, timeout=5.0)
+        if not response.ok:
+            logger.warning(
+                "GET request to Microsoft Graph failed with status code %s. Content:\n%s",
+                response.status_code,
+                response.text,
+            )
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Microsoft Graph API request failed",
+                    "message": f"GET request to Microsoft Graph failed with status code {response.status_code}.",
+                }
+            )
+            continue
+
+        alert_data = response.json()
+
+        # Update alert
+        if (
+            "assessment" in hit.howler
+            and hit.howler.assessment in properties_map["graph"]["classification"]
+            and hit.howler.assessment in properties_map["graph"]["determination"]
+        ):
+            classification = properties_map["graph"]["classification"][hit.howler.assessment]
+            determination = properties_map["graph"]["determination"][hit.howler.assessment]
+        else:
+            classification = alert_data["classification"]
+            determination = alert_data["determination"]
+
+        status = properties_map["graph"]["status"][hit.howler.status]
+        assigned_to = alert_data["assignedTo"]
+
+        data = {
+            "assignedTo": assigned_to,
+            "classification": classification,
+            "determination": determination,
+            "status": status,
+        }
+
+        response = requests.patch(
+            alert_url,
+            json=data,
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            timeout=5.0,
+        )
+        if not response.ok:
+            logger.warning(
+                "PATCH request to Microsoft Graph failed with status code %s. Content:\n%s",
+                response.status_code,
+                response.text,
+            )
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Microsoft Graph API request failed",
+                    "message": f"PATCH request to Microsoft Graph failed with status code {response.status_code}.",
+                }
+            )
+        else:
+            report.append(
+                {
+                    "query": f"howler.id:{hit.howler.id}",
+                    "outcome": "success",
+                    "title": "Alert updated in XDR Defender",
+                    "message": "Howler has successfully propagated changes to this alert to XDR Defender.",
+                }
+            )
+
+    return report
+
+
+def specification():
+    "Update Defender action specification"
+    return {
+        "id": OPERATION_ID,
+        "title": "Update Microsoft Defender XDR alert",
+        "priority": 8,
+        "description": {
+            "short": "Update Microsoft Defender XDR alert",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [{"args": {}, "options": {}, "validation": {}}],
+        "triggers": VALID_TRIGGERS,
+    }