howler-sentinel-plugin 0.2.0.dev137__tar.gz → 0.2.0.dev147__tar.gz

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/PKG-INFO

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

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "howler-sentinel-plugin"
-version = "0.2.0.dev137"
+version = "0.2.0.dev147"
 description = "A howler plugin for integration with Microsoft's Sentinel API"
 authors = [{ name = "CCCS", email = "analysis-development@cyber.gc.ca" }]
 license = { text = "MIT" }

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/sentinel/actions/send_to_sentinel.py

@@ -35,6 +35,8 @@ def execute(query: str, **kwargs) -> list[dict[str, Any]]:
         )
         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
@@ -52,7 +54,7 @@ def execute(query: str, **kwargs) -> list[dict[str, Any]]:
             continue
 
         try:
-            token, credentials = get_token(tenant_id, "https://monitor.azure.com/.default")
+            token = get_token(tenant_id, "https://monitor.azure.com/.default")
         except HowlerRuntimeError as err:
             logger.exception("Error on token fetching")
             report.append(
@@ -65,9 +67,24 @@ def execute(query: str, **kwargs) -> list[dict[str, Any]]:
             )
             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://{credentials['dce']}.ingest.monitor.azure.com/dataCollectionRules/{credentials['dcr']}/"
-            + f"streams/{credentials['table']}?api-version=2021-11-01-preview"
+            f"https://{ingestor.dce}.ingest.monitor.azure.com/dataCollectionRules/{ingestor.dcr}/"
+            + f"streams/{ingestor.table}?api-version=2021-11-01-preview"
         )
 
         payload = [

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/sentinel/actions/update_defender_xdr_alert.py

@@ -89,7 +89,7 @@ def execute(query: str, **kwargs):
             continue
 
         try:
-            token = get_token(tenant_id, "https://graph.microsoft.com/.default")[0]
+            token = get_token(tenant_id, "https://graph.microsoft.com/.default")
         except HowlerRuntimeError as err:
             logger.exception("Error on token fetching")
             report.append(

howler_sentinel_plugin-0.2.0.dev147/sentinel/config.py

@@ -0,0 +1,70 @@
+# mypy: ignore-errors
+import os
+from pathlib import Path
+from typing import Optional
+
+from howler.plugins.config import BasePluginConfig
+from pydantic import BaseModel, ImportString
+from pydantic_settings import SettingsConfigDict
+
+APP_NAME = os.environ.get("APP_NAME", "howler")
+PLUGIN_NAME = "sentinel"
+
+root_path = Path("/etc") / APP_NAME.replace("-dev", "").replace("-stg", "")
+
+config_locations = [
+    Path(__file__).parent / "manifest.yml",
+    root_path / "conf" / f"{PLUGIN_NAME}.yml",
+    Path(os.environ.get("HWL_CONF_FOLDER", root_path)) / f"{PLUGIN_NAME}.yml",
+]
+
+
+class ClientCredentials(BaseModel):
+    "OAuth2 credentials for client_credential OAuth2 Flow"
+
+    client_id: str
+    client_secret: str
+
+
+class Auth(BaseModel):
+    "Configuration for the various authentication methods, both to azure and incoming requests."
+
+    link_key: str = "abcdefghijklmnopqrstuvwxyz1234567890"
+
+    client_credentials: Optional[ClientCredentials] = None
+
+    custom_auth: Optional[ImportString] = None
+
+
+class Ingestor(BaseModel):
+    "Defines necessary data to ingest howler alerts into a specific azure tenancy"
+
+    tenant_id: str
+    dce: str
+    dcr: str
+    table: str
+
+
+class SentinelConfig(BasePluginConfig):
+    "Sentinel Plugin Configuration Model"
+
+    auth: Auth = Auth()
+
+    ingestors: list[Ingestor] = []
+
+    model_config = SettingsConfigDict(
+        yaml_file=config_locations,
+        yaml_file_encoding="utf-8",
+        strict=True,
+        env_nested_delimiter="__",
+        env_prefix=f"{PLUGIN_NAME.upper()}_",
+    )
+
+
+config = SentinelConfig()
+
+if __name__ == "__main__":
+    # When executed, the config model will print the default values of the configuration
+    import yaml
+
+    print(yaml.safe_dump(SentinelConfig().model_dump(mode="json")))  # noqa: T201

howler_sentinel_plugin-0.2.0.dev147/sentinel/manifest.yml

@@ -0,0 +1,13 @@
+name: sentinel
+modules:
+  odm:
+    modify_odm:
+      hit: true
+    generation:
+      hit: true
+  operations:
+    - azure_emit_hash
+    - send_to_sentinel
+    - update_defender_xdr_alert
+  routes:
+    - ingest:sentinel_api

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/sentinel/mapping/sentinel_incident.py

@@ -100,7 +100,7 @@ class SentinelIncident:
             # 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)
+            logger.info("Successfully mapped Sentinel Incident %s", incident_id)
             return bundle
 
         except Exception as exc:

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/sentinel/odm/hit.py

@@ -1,24 +1,33 @@
+from typing import TYPE_CHECKING
+
 import howler.odm as odm
 from howler.common.logging import get_logger
-from howler.odm.models.hit import Hit
+from howler.odm.models.azure import Azure
 
 from sentinel.odm.models.sentinel import Sentinel
 
+if TYPE_CHECKING:
+    from howler.odm.models.hit import Hit
+
+
 logger = get_logger(__file__)
 
 
 def modify_odm(target):
     "Add additional internal fields to the ODM"
-    logger.info("Modifying ODM with additional fields")
-
     target.add_namespace(
         "sentinel",
         odm.Optional(odm.Compound(Sentinel, description="Sentinel metadata associated with this alert")),
     )
 
 
-def generate_useful_hit(hit: Hit) -> Hit:
+def generate(hit: "Hit") -> "Hit":  # pragma: no cover
     "Add cccs-specific changes to hits on generation"
     hit.sentinel = Sentinel({"id": "example-sentinel-id"})
 
+    if not hit.azure:
+        hit.azure = Azure({"tenant_id": "example-tenant-id"})
+    else:
+        hit.azure.tenant_id = "example-tenant-id"
+
     return ["sentinel"], hit

{howler_sentinel_plugin-0.2.0.dev137 → howler_sentinel_plugin-0.2.0.dev147}/sentinel/routes/ingest.py

@@ -1,4 +1,3 @@
-import os
 import re
 from typing import Any
 
@@ -10,8 +9,8 @@ from howler.common.logging import get_logger
 from howler.common.swagger import generate_swagger_docs
 from howler.services import action_service, analytic_service, hit_service
 
-from ..mapping.sentinel_incident import SentinelIncident
-from ..mapping.xdr_alert import XDRAlert
+from sentinel.mapping.sentinel_incident import SentinelIncident
+from sentinel.mapping.xdr_alert import XDRAlert
 
 SUB_API = "sentinel"
 sentinel_api = make_subapi_blueprint(SUB_API, api_version=1)
@@ -19,12 +18,6 @@ sentinel_api._doc = "Ingest Microsoft Sentinel XDR incidents into Howler"
 
 logger = get_logger(__file__)
 
-# For testing purposes, replace with actual secret in production
-SECRET = os.environ.get("SENTINEL_LINK_KEY", "abcdefghijklmnopqrstuvwxyz1234567890")
-
-if SECRET.startswith("abcdef"):
-    logger.warning("Default secret used!")
-
 
 @generate_swagger_docs()
 @sentinel_api.route("/ingest", methods=["POST"])
@@ -77,8 +70,14 @@ def ingest_xdr_incident(**kwargs) -> tuple[dict[str, Any], int]:  # noqa C901
         Receives a Microsoft Sentinel XDR incident as JSON, maps it to Howler format, and creates or updates a bundle
         and its underlying alerts in Howler. Returns details about the created or updated bundle and alerts.
     """
+    from sentinel.config import config
+
+    # API Key authentication
     apikey = request.headers.get("Authorization", "Basic ", type=str).split(" ")[1]
-    if not apikey or apikey != SECRET:
+
+    link_key = config.auth.link_key
+
+    if not apikey or apikey != link_key:
         return unauthorized(err="API Key does not match expected value.")
 
     logger.info("Received authorization header with value %s", re.sub(r"^(.{3}).+(.{3})$", r"\1...\2", apikey))

howler_sentinel_plugin-0.2.0.dev147/sentinel/utils/tenant_utils.py

@@ -0,0 +1,56 @@
+import sys
+from typing import Optional
+
+import requests
+from howler.common.exceptions import HowlerRuntimeError
+from howler.common.logging import get_logger
+from howler.config import cache
+
+logger = get_logger(__file__)
+
+
+def skip_cache(*args):
+    "Function to skip cache in testing mode"
+    return "pytest" in sys.modules
+
+
+@cache.memoize(15 * 60, unless=skip_cache)
+def get_token(tenant_id: str, scope: str) -> Optional[str]:
+    """Get a borealis token based on the current howler token"""
+    from sentinel.config import config
+
+    token = None
+
+    if config.auth.client_credentials:
+        logger.info(
+            "Using client_credentials flow for client id %s with scope %s",
+            config.auth.client_credentials.client_id,
+            scope,
+        )
+
+        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": config.auth.client_credentials.client_id,
+                "client_secret": config.auth.client_credentials.client_secret,
+                "scope": scope,
+            },
+            timeout=5.0,
+        )
+
+        if not response.ok:
+            raise HowlerRuntimeError(
+                "Authentication to Azure Monitor API using client_credentials flow failed with status code"
+                f" {response.status_code}. Response:\n{response.text}"
+            )
+
+        token = response.json()["access_token"]
+    elif config.auth.custom_auth:
+        token = config.auth.custom_auth(tenant_id, scope)
+
+    if not token:
+        logger.warning("No access token received")
+
+    return token

howler_sentinel_plugin-0.2.0.dev137/sentinel/routes/__init__.py

@@ -1,5 +0,0 @@
-from flask.blueprints import Blueprint
-
-from sentinel.routes.ingest import sentinel_api
-
-ROUTES: list[Blueprint] = [sentinel_api]

howler_sentinel_plugin-0.2.0.dev137/sentinel/utils/tenant_utils.py

@@ -1,40 +0,0 @@
-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, scope: 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.")
-
-    logger.info("Generating client credential token for client id %s with scope %s", credentials["client_id"], scope)
-
-    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": scope,
-        },
-        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