howler-sentinel-plugin 0.2.0.dev87__py3-none-any.whl → 0.2.0.dev95__py3-none-any.whl

{howler_sentinel_plugin-0.2.0.dev87.dist-info → howler_sentinel_plugin-0.2.0.dev95.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: howler-sentinel-plugin
-Version: 0.2.0.dev87
+Version: 0.2.0.dev95
 Summary: A howler plugin for integration with Microsoft's Sentinel API
 License: MIT
 Author: CCCS

{howler_sentinel_plugin-0.2.0.dev87.dist-info → howler_sentinel_plugin-0.2.0.dev95.dist-info}/RECORD

@@ -1,6 +1,8 @@
 sentinel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sentinel/actions/ingestion.py,sha256=_t7wrmozhoT_MmktDmNxYiXrA1Q0LCiDt0rTwHBkwbc,1669
+sentinel/actions/send_to_sentinel.py,sha256=REclVHxuG0Q5PIXZ-13crQhoz8BmJJJyTc6suzpq0m0,3227
 sentinel/actions/synchronization.py,sha256=g5c34410zINWb4fSEzj94drnk5alRj_ju9xMrB39z0s,1818
+sentinel/actions/update_defender_xdr_alert.py,sha256=y6xCUFp6xpR1u1uAZd9CeK_sV9acwHamkXBTD_3cHg8,6848
 sentinel/mapping/sentinel_incident.py,sha256=3QBnP6qFpJgE3pHvx5VvFnB3m2TVOoWxs8OysDlJVV8,9547
 sentinel/mapping/xdr_alert.py,sha256=UPoqdZsjUXmJz0dCf_qMlh9Jr0D2HcSNOFvbg8lE4wY,18250
 sentinel/mapping/xdr_alert_evidence.py,sha256=q622G4eZwFR3TCj418ZCpE83DGVicrWIQZo8Gkj_3FM,31323
@@ -8,8 +10,9 @@ sentinel/odm/hit.py,sha256=hAuO2ONMK3Ml8Xu6E7tHrmZ7M6HG5tT38RD9ZxwY254,666
 sentinel/odm/models/sentinel.py,sha256=XT3XdT92uoCV5vmY9dT1jmcxRyuu9vp1gE8AwZdKBIc,337
 sentinel/routes/__init__.py,sha256=JYmKRwIfEsiPos1XuMQ2mlGDbxk6TN_cVEM0K_RNze4,130
 sentinel/routes/ingest.py,sha256=_9OdOw_9nBJseKIBnmHDLjnqZ_bDdM4wfLpLrek4-ak,7018
-howler_sentinel_plugin-0.2.0.dev87.dist-info/LICENSE,sha256=Wg2luVnxEkP2NSn11nh1US6W_nFFbICBAVTG9iG3t5M,1091
-howler_sentinel_plugin-0.2.0.dev87.dist-info/METADATA,sha256=pjJIO2K9im-8T5bIEUMxXy92S07JkF-9cpRs84dQpys,748
-howler_sentinel_plugin-0.2.0.dev87.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-howler_sentinel_plugin-0.2.0.dev87.dist-info/entry_points.txt,sha256=4IJyMY0V49s3Wp659ngN_7U8g66-czeKxI-_dNAFP5g,60
-howler_sentinel_plugin-0.2.0.dev87.dist-info/RECORD,,
+sentinel/utils/tenant_utils.py,sha256=W7kBtxYNhs3vcgMf78eIRqiTpDtqjzEI2H2d0papQ_Q,1224
+howler_sentinel_plugin-0.2.0.dev95.dist-info/LICENSE,sha256=Wg2luVnxEkP2NSn11nh1US6W_nFFbICBAVTG9iG3t5M,1091
+howler_sentinel_plugin-0.2.0.dev95.dist-info/METADATA,sha256=ivfqDB5AuHiiNXVlA5CcbdB0N-yS1qQuZ86gau729mM,748
+howler_sentinel_plugin-0.2.0.dev95.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+howler_sentinel_plugin-0.2.0.dev95.dist-info/entry_points.txt,sha256=4IJyMY0V49s3Wp659ngN_7U8g66-czeKxI-_dNAFP5g,60
+howler_sentinel_plugin-0.2.0.dev95.dist-info/RECORD,,

sentinel/actions/send_to_sentinel.py

@@ -0,0 +1,102 @@
+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):
+    """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
+
+    for hit in hits:
+        try:
+            token, credentials = get_token(hit.azure.tenant_id)
+        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
+
+        uri = (
+            f"https://{credentials['dce']}.ingest.monitor.azure.com/dataCollectionRules/{credentials['dcr']}/"
+            + f"streams/{credentials['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:
+            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 successfuly 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,192 @@
+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:
+        try:
+            token, credentials = get_token(hit.azure.tenant_id)
+        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
+
+        token_request_url = f"https://login.microsoftonline.com/{hit.azure.tenant_id}/oauth2/v2.0/token"
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": credentials["client_id"],
+            "client_secret": credentials["client_secret"],
+            "scope": "https://graph.microsoft.com/.default",
+        }
+        response = requests.post(token_request_url, data=data, timeout=5.0)
+
+        if not response.ok:
+            logger.warning("Failed to authenticate to Microsoft Graph.")
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Authentication failed",
+                    "message": f"Authentication to Microsoft Graph API failed with status code {response.status_code}.",
+                }
+            )
+            continue
+
+        token = response.json()["access_token"]
+
+        # 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.", response.status_code)
+            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:
+            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}.",
+                }
+            )
+
+        report.append(
+            {
+                "query": f"howler.id:{hit.howler.id}",
+                "outcome": "success",
+                "title": "Alert updated in XDR Defender",
+                "message": "Howler has successfuly 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,
+    }

sentinel/utils/tenant_utils.py

@@ -0,0 +1,38 @@
+import json
+import os
+
+import requests
+from howler.common.exceptions import HowlerRuntimeError
+from howler.common.logging import get_logger
+from howler.config import cache
+
+logger = get_logger(__file__)
+
+
+@cache.memoize(15 * 60)
+def get_token(tenant_id: str) -> tuple[str, dict[str, str]]:
+    """Get a borealis token based on the current howler token"""
+    # Get bearer token
+    try:
+        credentials = json.loads(os.environ["HOWLER_SENTINEL_INGEST_CREDENTIALS"])
+    except (KeyError, json.JSONDecodeError):
+        raise HowlerRuntimeError("Credential data not configured.")
+
+    token_request_url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
+    response = requests.post(
+        token_request_url,
+        data={
+            "grant_type": "client_credentials",
+            "client_id": credentials["client_id"],
+            "client_secret": credentials["client_secret"],
+            "scope": "https://monitor.azure.com/.default",
+        },
+        timeout=5.0,
+    )
+
+    if not response.ok:
+        raise HowlerRuntimeError(f"Authentication to Azure Monitor API failed with status code {response.status_code}.")
+
+    token = response.json()["access_token"]
+
+    return token, credentials