howler-sentinel-plugin 0.2.0.dev68__py3-none-any.whl → 0.2.0.dev92__py3-none-any.whl

{howler_sentinel_plugin-0.2.0.dev68.dist-info → howler_sentinel_plugin-0.2.0.dev92.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: howler-sentinel-plugin
-Version: 0.2.0.dev68
+Version: 0.2.0.dev92
 Summary: A howler plugin for integration with Microsoft's Sentinel API
 License: MIT
 Author: CCCS
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
 Description-Content-Type: text/markdown
 
 # Howler Sentinel Plugin

howler_sentinel_plugin-0.2.0.dev92.dist-info/RECORD

@@ -0,0 +1,17 @@
+sentinel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sentinel/actions/ingestion.py,sha256=_t7wrmozhoT_MmktDmNxYiXrA1Q0LCiDt0rTwHBkwbc,1669
+sentinel/actions/send_to_sentinel.py,sha256=qxYPHqsA2jbEiQG1qJdnIVQkdvxlL1gyPXNmOUVYnmk,3280
+sentinel/actions/synchronization.py,sha256=g5c34410zINWb4fSEzj94drnk5alRj_ju9xMrB39z0s,1818
+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
+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
+sentinel/utils/tenant_utils.py,sha256=W7kBtxYNhs3vcgMf78eIRqiTpDtqjzEI2H2d0papQ_Q,1224
+howler_sentinel_plugin-0.2.0.dev92.dist-info/LICENSE,sha256=Wg2luVnxEkP2NSn11nh1US6W_nFFbICBAVTG9iG3t5M,1091
+howler_sentinel_plugin-0.2.0.dev92.dist-info/METADATA,sha256=JxB76pRL1VAh9GWtDRhdo3ls9xtATvSwzpeU7vWubzU,748
+howler_sentinel_plugin-0.2.0.dev92.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+howler_sentinel_plugin-0.2.0.dev92.dist-info/entry_points.txt,sha256=4IJyMY0V49s3Wp659ngN_7U8g66-czeKxI-_dNAFP5g,60
+howler_sentinel_plugin-0.2.0.dev92.dist-info/RECORD,,

sentinel/actions/send_to_sentinel.py

@@ -0,0 +1,103 @@
+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,
+        "i18nKey": "Send hit to Microsoft Sentinel",
+        "description": {
+            "short": "Send hit to Microsoft Sentinel",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [{"args": {}, "options": {}, "validation": {}}],
+        "triggers": VALID_TRIGGERS,
+    }

sentinel/mapping/sentinel_incident.py

@@ -0,0 +1,234 @@
+"""Sentiel Incident mapper for converting Microsoft Sentinel Sentiel Incidents to Howler bundles."""
+
+import logging
+from typing import Any, Optional
+
+from dateutil import parser
+
+# Use standard logging for now
+logger = logging.getLogger(__name__)
+
+
+class SentinelIncident:
+    """Class to handle mapping of Sentiel Incidents to Howler bundles."""
+
+    DEFAULT_CUSTOMER_NAME = "Unknown Customer"
+
+    def __init__(self, tid_mapping: Optional[dict[str, str]] = None):
+        """Initialize the Sentiel Incident mapper.
+
+        Args:
+            tid_mapping: Mapping of tenant IDs to customer names
+        """
+        self.tid_mapping = tid_mapping or {}
+
+    # --- Public mapping methods ---
+
+    def map_incident_to_bundle(self, sentinel_incident: dict[str, Any]) -> Optional[dict[str, Any]]:
+        """Map an Sentiel Incident to a Howler bundle.
+
+        Args:
+            sentinel_incident (dict[str, Any]): The Sentiel Incident data from Microsoft Graph.
+
+        Returns:
+            Optional[dict[str, Any]]: Mapped bundle dictionary or None if mapping fails.
+
+        Example:
+            >>> mapper = SentinelIncident()
+            >>> bundle = mapper.map_incident_to_bundle(sentinel_incident)
+        """
+        try:
+            if not sentinel_incident:
+                logger.error("Empty incident data provided")
+                return None
+
+            required_fields = ["id", "tenantId", "createdDateTime"]
+            for field in required_fields:
+                if not sentinel_incident.get(field):
+                    logger.warning("Missing required field '%s' in incident: %s", field, sentinel_incident)
+
+            tenant_id: str = sentinel_incident.get("tenantId", "")
+            customer_name: str = self.get_customer_name(tenant_id)
+
+            incident_id: Optional[str] = sentinel_incident.get("id")
+            status: str = sentinel_incident.get("status", "active")
+            display_name: str = sentinel_incident.get("displayName", "")
+            created_datetime: Optional[str] = sentinel_incident.get("createdDateTime")
+            assigned_to: Optional[str] = sentinel_incident.get("assignedTo")
+            classification: str = sentinel_incident.get("classification", "unknown")
+            severity: str = sentinel_incident.get("severity", "medium")
+            custom_tags: list[str] = sentinel_incident.get("customTags") or []
+            system_tags: list[str] = sentinel_incident.get("systemTags") or []
+            description: str = sentinel_incident.get("description", "")
+            resolving_comment: str = sentinel_incident.get("resolvingComment", "")
+            if not isinstance(custom_tags, list):
+                logger.warning("customTags is not a list: %s", custom_tags)
+                custom_tags = []
+            if not isinstance(system_tags, list):
+                logger.warning("systemTags is not a list: %s", system_tags)
+                system_tags = []
+
+            bundle: dict[str, Any] = {
+                "howler": {
+                    "status": self.map_sentinel_status_to_howler(status),
+                    "detection": display_name,
+                    "assignment": self.map_sentinel_user_to_howler(assigned_to),
+                    "score": self.map_severity_to_score(severity),
+                    "outline.summary": description,
+                    "rationale": resolving_comment,
+                    "analytic": "MSGraph",
+                    "is_bundle": True,
+                    "bundle_size": 0,
+                    "hits": [],
+                    "labels.generic": self._build_labels(custom_tags, system_tags),
+                },
+                "organization": {"name": customer_name, "id": tenant_id},
+                "sentinel": {
+                    "id": incident_id,
+                },
+                "evidence": {"cloud": {"account": {"id": tenant_id}}},
+                "event": {
+                    "created": created_datetime,
+                    "start": created_datetime,
+                    "end": created_datetime,
+                },
+            }
+            self._map_graph_host_link(sentinel_incident, bundle)
+            self._map_timestamps(sentinel_incident, bundle)
+            # Add assessment conditionally if classification is not null
+            if classification is not None:
+                bundle["howler"]["assessment"] = self.map_classification(classification)
+            logger.info("Successfully mapped Sentiel Incident %s", incident_id)
+            return bundle
+
+        except Exception as exc:
+            logger.error("Failed to map Sentiel Incident: %s", exc, exc_info=True)
+            return None
+
+    def get_customer_name(self, tid: str) -> str:
+        """Get customer name from tenant ID, return default if not found.
+
+        Args:
+            tid (str): Tenant ID.
+        Returns:
+            str: Customer name or default.
+        """
+        return self.tid_mapping.get(tid, self.DEFAULT_CUSTOMER_NAME)
+
+    def map_sentinel_status_to_howler(self, sentinel_status: str) -> str:
+        """Map Sentiel Incident status to Howler status.
+
+        Args:
+            sentinel_status (str): Sentinel status string.
+        Returns:
+            str: Howler status string.
+        """
+        status_mapping: dict[str, str] = {
+            "new": "open",
+            "active": "in-progress",
+            "inProgress": "in-progress",
+            "resolved": "resolved",
+            "closed": "resolved",
+        }
+        return status_mapping.get(sentinel_status, "open")
+
+    def map_sentinel_user_to_howler(self, sentinel_user: Optional[str]) -> str:
+        """Map Sentinel user assignment to Howler format.
+
+        Args:
+            sentinel_user (Optional[str]): Sentinel user assignment.
+        Returns:
+            str: Howler assignment string.
+        """
+        if not sentinel_user or sentinel_user in ["null", "None"]:
+            return "unassigned"
+        return sentinel_user
+
+    def map_severity_to_score(self, severity: str) -> int:
+        """Map string severity to numeric score.
+
+        Args:
+            severity (str): Severity string.
+        Returns:
+            int: Numeric score.
+        """
+        severity_mapping: dict[str, int] = {"low": 25, "medium": 50, "high": 75, "critical": 100}
+        return severity_mapping.get(severity.lower() if severity else "medium", 50)
+
+    def map_classification(self, classification: str) -> str:
+        """Map Sentinel classification to Howler assessment.
+
+        Args:
+            classification (str): Sentinel classification string.
+        Returns:
+            str: Howler assessment string.
+        """
+        classification_mapping: dict[str, str] = {
+            "unknown": "ambiguous",
+            "truePositive": "compromise",
+            "falsePositive": "false-positive",
+            "informationalExpectedActivity": "legitimate",
+            "benignPositive": "legitimate",
+        }
+        return classification_mapping.get(classification, "")
+
+    # --- Private helper methods ---
+
+    def _map_graph_host_link(self, graph_alert: dict[str, Any], howler_hit: dict[str, Any]) -> None:
+        """Map Graph host link from Graph alert to Howler hit.
+
+        Args:
+            graph_alert (dict[str, Any]): Graph alert data.
+            howler_hit (dict[str, Any]): Howler hit/bundle to update.
+        """
+        link: dict[str, str] = {
+            "icon": "https://security.microsoft.com/favicon.ico",
+            "title": "Open in Microsoft Sentinel portal",
+            "href": graph_alert.get("incidentWebUrl", ""),
+        }
+        if graph_alert.get("incidentWebUrl"):
+            howler_hit["howler"]["links"] = howler_hit["howler"].get("links", [])
+            howler_hit["howler"]["links"].append(link)
+
+    def _map_timestamps(self, graph_alert: dict[str, Any], howler_hit: dict[str, Any]) -> None:
+        """Map timestamps from Graph alert to Howler hit.
+
+        Args:
+            graph_alert (dict[str, Any]): Graph alert data.
+            howler_hit (dict[str, Any]): Howler hit/bundle to update.
+        """
+        for time_field in [
+            "createdDateTime",
+            "lastUpdateDateTime",
+            "firstActivityDateTime",
+            "lastActivityDateTime",
+        ]:
+            timestamp: Optional[str] = graph_alert.get(time_field)
+            if timestamp:
+                try:
+                    dt_obj = parser.isoparse(timestamp)
+                    if time_field == "createdDateTime":
+                        howler_hit["event"]["created"] = dt_obj.isoformat()
+                    elif time_field == "firstActivityDateTime":
+                        howler_hit["event"]["start"] = dt_obj.isoformat()
+                    elif time_field == "lastActivityDateTime":
+                        howler_hit["event"]["end"] = dt_obj.isoformat()
+                except Exception as exc:
+                    logger.warning("Invalid timestamp format for %s: %s (%s)", time_field, timestamp, exc)
+
+    def _build_labels(self, custom_tags: list[str], system_tags: list[str]) -> list[str]:
+        """Build combined labels from custom and system tags.
+
+        Args:
+            custom_tags (list[str]): Custom tags.
+            system_tags (list[str]): System tags.
+        Returns:
+            list[str]: Combined label list.
+        """
+        labels: list[str] = []
+        if custom_tags:
+            labels.extend(custom_tags)
+        if system_tags:
+            labels.extend(["system_%s" % tag for tag in system_tags])
+        labels.append("sentinel_incident")
+        return labels