microsoft-graph-helpers 0.1.0__py3-none-any.whl

microsoft_graph_helpers/__init__.py

@@ -0,0 +1,30 @@
+from .api_token import (
+    get_bearer_token,
+)
+
+from .core import (
+    get_headers,
+    make_graph_api_request,
+    handle_graph_api_error
+)
+
+from .email import (
+    send_message_as,
+    retrieve_message
+)
+
+from .groups import (
+    get_group_guid,
+    get_group_members,
+)
+
+from .security import (
+    run_hunting_query,
+)
+
+from .users import (
+    verify_user_exists,
+    revoke_ms_sessions,
+    reset_ms_password,
+    get_user_direct_group_memberships,
+)

microsoft_graph_helpers/api_token.py

@@ -0,0 +1,92 @@
+import hashlib
+import json
+import logging
+import requests
+import time
+
+# In-memory token cache
+_token_cache = {}
+
+def _generate_cache_key(tenant_id, client_id, secret, scope):
+    key_string = f"{tenant_id}:{client_id}:{secret}:{scope}"
+    return hashlib.sha256(key_string.encode()).hexdigest()
+
+def get_bearer_token(
+    tenant_id: str,
+    client_id: str,
+    client_secret: str,
+    scope: str = "https://graph.microsoft.com/.default"
+) -> str:
+    """
+    Fetches a bearer token from Microsoft Identity Platform using client credentials.
+    This function uses an in-memory cache to avoid redundant token requests.
+
+    Args:
+        tenant_id (str): Azure AD tenant ID.
+        client_id (str): Application (client) ID.
+        client_secret (str): Application secret.
+        scope (str, optional): OAuth2 scope. Defaults to Microsoft Graph.
+
+    Returns:
+        str: Access token string.
+
+    Raises:
+        TokenRequestError: If the token request fails or returns a non-200 response.
+        RuntimeError: If the response is not valid JSON or if the request times out.
+    """
+    logging.debug(f"get_bearer_token called for tenant_id={tenant_id[:5]}..., client_id={client_id[:5]}...")
+    cache_key = _generate_cache_key(tenant_id, client_id, client_secret, scope)
+    cached = _token_cache.get(cache_key)
+
+    if cached and cached['expires_at'] > time.time():
+        logging.debug(f"Retrieved cached Microsoft Graph token: {cache_key}")
+        return cached['token']
+
+    logging.debug(f"No valid cached Microsoft Graph token found for key: {cache_key}")
+    token_url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
+    data = {
+        'client_id': client_id,
+        'client_secret': client_secret,
+        'scope': scope,
+        'grant_type': 'client_credentials'
+    }
+    headers = {
+        'Content-Type': 'application/x-www-form-urlencoded'
+    }
+
+    try:
+        response = requests.post(token_url, data=data, headers=headers, timeout=10)
+        try:
+            response_json = response.json()
+        except ValueError:
+            logging.critical("Non-JSON response received when retrieving Microsoft Graph token.")
+            raise RuntimeError("Invalid JSON response received when retrieving Microsoft Graph token.")
+
+        if response.status_code == 200:
+            token = response_json.get('access_token')
+            if not token:
+                logging.critical("Microsoft Graph token not found in the response.")
+                raise RuntimeError("Microsoft Graph token not found in the response.")
+
+            expires_in = response_json.get('expires_in', 3599)
+            _token_cache[cache_key] = {
+                'token': token,
+                'expires_at': time.time() + expires_in - 60
+            }
+
+            logging.debug(
+                f"Obtained Microsoft Graph bearer token with expiry at {time.ctime(_token_cache[cache_key]['expires_at'])}."
+            )
+            return token
+
+        error_dump = dict({'http_status_code': response.status_code}, **response_json)
+        logging.critical(json.dumps(error_dump))
+        raise TokenRequestError(json.dumps(error_dump, indent=4))
+
+    except requests.exceptions.Timeout:
+        logging.critical("Microsoft Graph token request timed out.")
+        raise RuntimeError("Microsoft Graph token request timed out.")
+
+class TokenRequestError(Exception):
+    """Raised when a Microsoft Graph token request fails."""
+    pass

microsoft_graph_helpers/core.py

@@ -0,0 +1,79 @@
+import json, logging, requests, time
+from typing import List, Union
+from requests.exceptions import Timeout, RequestException
+
+
+def get_headers(bearer_token):
+    # returns basic request header for making Graph calls
+    return {
+        'Content-Type': 'application/json',
+        'Authorization': 'Bearer ' + bearer_token
+    }
+
+def make_graph_api_request(
+    method: str,
+    url: str,
+    headers: dict,
+    payload: Union[dict, None] = None,
+    context: str = "",
+    retries: int = 3,
+    timeout: int = 15
+) -> Union[dict, bool]:
+    for attempt in range(1, retries + 1):
+        try:
+            if method.upper() == "GET":
+                response = requests.get(url, headers=headers, timeout=timeout)
+            elif method.upper() == "POST":
+                response = requests.post(url, headers=headers, json=payload, timeout=timeout)
+            elif method.upper() == "PATCH":
+                response = requests.patch(url, headers=headers, json=payload, timeout=timeout)
+            else:
+                logging.error(f"[{context}] Unsupported HTTP method: {method}")
+                return False
+
+            if response.status_code in (200, 202, 204):
+                if response.status_code == 204:
+                    logging.debug(f"[{context}] Http Status Code: {response.status_code} - Request submitted successfully.")
+                    return True
+                elif response.status_code == 202:
+                    logging.debug(f"[{context}] Http Status Code: {response.status_code} - Request submitted successfully.")
+                    return True
+                try:
+                    return response.json()
+                except ValueError:
+                    logging.warning(f"[{context}] Http Status Code: {response.status_code} - Response returned no JSON content.")
+                    return True
+            else:
+                handle_graph_api_error(response, context=context)
+                return False
+
+        except Timeout:
+            logging.warning(f"[{context}] Timeout on attempt {attempt}/{retries}. Retrying...")
+        except RequestException as e:
+            logging.error(f"[{context}] RequestException: {e}")
+            break
+
+        time.sleep(2 ** attempt)
+
+    logging.error(f"[{context}] All retry attempts failed.")
+    return False
+
+def handle_graph_api_error(response: requests.Response, context: str = "") -> None:
+    """
+    Handles and logs errors from Microsoft Graph API responses.
+    """
+    status_code = response.status_code
+
+    try:
+        result = response.json()
+        error = result.get("error", {})
+        code = error.get("code", "UnknownError")
+        message = error.get("message", "No error message provided.")
+    except (ValueError, AttributeError) as e:
+        code = "InvalidResponse"
+        message = f"Failed to parse error response: {e}"
+        logging.error(f"Raw response: {response.text}")
+
+    prefix = f"[{context}] " if context else ""
+    logging.warning(f"{prefix}Http Status Code: {status_code} - {code}.")
+    logging.warning(f"{prefix}{message}")

microsoft_graph_helpers/email.py

@@ -0,0 +1,88 @@
+import json, logging, requests, urllib.parse
+from typing import List, Tuple, Union
+from .core import get_headers, make_graph_api_request
+
+
+def send_message_as(
+    bearer_token: str,
+    sender_email: str,
+    recipient_email: str,
+    subject: str,
+    body: str,
+    save_to_sent_messages: bool = False,
+) -> bool:
+    logging.debug(f"Sending message from {sender_email} to {recipient_email}")
+    headers = get_headers(bearer_token)
+    payload = {
+        "message": {
+            "subject": subject,
+            "body": {
+                "contentType": "Text",
+                "content": body
+            },
+            "toRecipients": [
+                {
+                    "emailAddress": {
+                        "address": recipient_email
+                    }
+                }
+            ]
+        },
+        "saveToSentItems": str(save_to_sent_messages).lower()
+    }
+
+    response = make_graph_api_request(
+        method="POST",
+        url=f"https://graph.microsoft.com/v1.0/users/{sender_email}/sendMail",
+        headers=headers,
+        payload=payload,
+        timeout=10,
+        context="send_message_as",
+    )
+    if response == True:
+        logging.debug(f"[send_message_as] Message sent to {recipient_email}")
+    else:
+        logging.debug(f"[send_message_as] Failed to send message to {recipient_email}")
+    return response
+
+
+def retrieve_message(
+    bearer_token: str,
+    user_principal_name: str,
+    internet_message_id: str
+) -> Tuple[Union[dict, None], Union[str, None]]:
+    """
+    Searches for a message by its Internet Message ID across multiple folders
+    in the user's mailbox.
+
+    Returns:
+        Tuple[dict or None, str or None]: The message object and the folder name it was found in.
+    """
+    logging.debug(f"Searching for message ID \"{internet_message_id}\" in mailbox \"{user_principal_name}\"")
+    encoded_id = urllib.parse.quote(internet_message_id)
+    headers = get_headers(bearer_token)
+    folders = [
+        ("Messages", f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/messages?$filter=internetMessageId eq '{encoded_id}'"),
+        ("DeletedItems", f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/mailFolders/DeletedItems/messages?$filter=internetMessageId eq '{encoded_id}'"),
+        ("RecoverableItemsDeletions", f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/mailFolders/RecoverableItemsDeletions/messages?$filter=internetMessageId eq '{encoded_id}'"),
+        ("RecoverableItemsPurges", f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/mailFolders/RecoverableItemsPurges/messages?$filter=internetMessageId eq '{encoded_id}'"),
+        ("RecoverableItemsDiscoveryHolds", f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/mailFolders/RecoverableItemsDiscoveryHolds/messages?$filter=internetMessageId eq '{encoded_id}'")
+    ]
+
+    for folder_name, url in folders:
+        logging.debug(f"Checking folder: {folder_name}")
+        response = make_graph_api_request(
+            method="GET",
+            url=url,
+            headers=headers,
+            timeout=10,
+            context=f"retrieve_message:{folder_name}"
+        )
+
+        if isinstance(response, dict) and response.get("value"):
+            logging.info(f"[retrieve_message] Message found in folder: {folder_name}")
+            return response, folder_name
+
+    logging.warning(f"Message ID \"{internet_message_id}\" not found in any folder for user \"{user_principal_name}\".")
+    return None, None
+

microsoft_graph_helpers/groups.py

@@ -0,0 +1,40 @@
+import json, logging, requests
+from .core import get_headers, make_graph_api_request
+
+def get_group_guid(bearer_token: str, group_name: str):
+    logging.debug(f"Obtaining GUID for group named {group_name} from Microsoft Graph API.")
+
+    url = f"https://graph.microsoft.com/v1.0/groups?$filter=displayName eq '{group_name}'"
+    headers = get_headers(bearer_token)
+    response = make_graph_api_request(
+        method="GET",
+        url=url,
+        headers=headers,
+        context="get_group_guid"
+    )
+    if isinstance(response, dict):
+        value = response.get("value", [])
+        if len(value) > 1:
+            logging.warning(f"Multiple groups found with name '{group_name}'. Returning the first match.")
+        if value and isinstance(value, list):
+            return value[0].get("id")
+    return False
+
+
+def get_group_members(bearer_token: str, guid: str):
+    logging.debug(f"Obtaining members of group whose GUID is {guid} from Microsoft Graph API.")
+
+    url = f"https://graph.microsoft.com/v1.0/groups/{guid}/members"
+    headers = get_headers(bearer_token)
+
+    response = make_graph_api_request(
+        method="GET",
+        url=url,
+        headers=headers,
+        context="get_group_members"
+    )
+    if isinstance(response, dict) and 'value' in response:
+        logging.debug(f"Response from Microsoft Graph API contained {len(response['value'])} members.")
+        return [member.get('mail') for member in response['value'] if member.get('mail')]
+    return False
+

microsoft_graph_helpers/security.py

@@ -0,0 +1,26 @@
+import json, logging, requests
+from typing import List, Union
+from .core import get_headers, make_graph_api_request
+
+def run_hunting_query(bearer_token: str, query: str, timespan: str = "P90D") -> Union[List[dict], bool]:
+    logging.debug("Submitting Hunting Query as POST request to Graph API.")
+
+    url = "https://graph.microsoft.com/v1.0/security/runHuntingQuery"
+    headers = get_headers(bearer_token)
+    payload = {
+        "Query": query,
+        "Timespan": timespan
+    }
+
+    response = make_graph_api_request(
+        method="POST",
+        url=url,
+        headers=headers,
+        payload=payload,
+        context="run_hunting_query"
+    )
+
+    if isinstance(response, dict) and "results" in response:
+        logging.debug("200: Hunting query received successful response")
+        return response["results"]
+    return False

microsoft_graph_helpers/users.py

@@ -0,0 +1,85 @@
+import json, logging, requests
+from .core import get_headers, make_graph_api_request
+
+def verify_user_exists(bearer_token, user_principal_name):
+    logging.debug(f"Querying Microsoft Graph for user {user_principal_name}")
+    url = f"https://graph.microsoft.com/v1.0/users/{user_principal_name}"
+    headers = get_headers(bearer_token)
+
+    response = make_graph_api_request(
+        method="GET",
+        url=url,
+        headers=headers,
+        context="verify_user_exists"
+    )
+
+    if response is False:
+        logging.debug(f"[verify_user_exists] User {user_principal_name} not found.")
+        return False
+    else:
+        logging.debug(f"[verify_user_exists] User {user_principal_name} exists.")
+        return True
+
+
+def revoke_ms_sessions(bearer_token, user_principal_name):
+    logging.debug(f"[revoke_ms_sessions] Revoking sign-in sessions for {user_principal_name}")
+
+    url = f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/revokeSignInSessions"
+    headers = get_headers(bearer_token)
+    response = make_graph_api_request(
+        method="POST",
+        url=url,
+        headers=headers,
+        context="revoke_ms_sessions"
+    )
+
+    if response is False:
+        logging.debug(f"[revoke_ms_sessions] for {user_principal_name} failed.")
+        return False
+    logging.debug(f"[revoke_ms_sessions] for {user_principal_name} succeeded.")
+    return True
+
+
+def reset_ms_password(bearer_token, user_principal_name, password):
+    logging.debug(f"[reset_ms_password] Resetting password for {user_principal_name}.")
+
+    url = f"https://graph.microsoft.com/v1.0/users/{user_principal_name}"
+    headers = get_headers(bearer_token)
+    headers.update({'Accept': "application/json"})
+    payload = {
+        'passwordProfile': {
+            'forceChangePasswordNextSignIn': False,
+            'password': password
+        }
+    }
+
+    response = make_graph_api_request(
+        method="PATCH",
+        url=url,
+        headers=headers,
+        payload=payload,
+        context="reset_ms_password"
+    )
+    if response is False:
+        logging.debug(f"reset_ms_password] Failed to reset password for {user_principal_name}.")
+        return False
+    logging.debug(f"[reset_ms_password] Reset password for {user_principal_name}.")
+    return False
+
+
+def get_user_direct_group_memberships(bearer_token, user_principal_name):
+    logging.debug(f"[get_user_direct_group_memberships] Fetching group memberships for {user_principal_name}.")
+
+    url = f"https://graph.microsoft.com/v1.0/users/{user_principal_name}/memberOf"
+    headers = get_headers(bearer_token)
+    response = make_graph_api_request(
+        method="GET",
+        url=url,
+        headers=headers,
+        context="get_user_direct_group_memberships"
+    )
+    if response is False:
+        logging.debug(f"Failed to fetch group memberships for {user_principal_name}.")
+        return False
+    logging.debug(f"Succeeded in fetching group memberships for {user_principal_name}.")
+    return response

microsoft_graph_helpers-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: microsoft_graph_helpers
+Version: 0.1.0
+Summary: Helper functions for interacting with Microsoft Graph API
+Author: Lucas Krupinski
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.5
+Dynamic: requires-python
+
+# Microsoft Graph Helpers
+
+A Python module for calling various Microsoft Graph endpoints. Not nearly as comprehensive as Microsoft's official modules, but far lighter weight and with a minimal amount of dependencies.
+
+Not comprehensive, only contains calls that I've needed to user in my other applets.

microsoft_graph_helpers-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+microsoft_graph_helpers/__init__.py,sha256=S07qPxI-j7FQVKVjvSGPO6QFNcSWueEein1xwyXtmS0,462
+microsoft_graph_helpers/api_token.py,sha256=5B_GeOeIdI-D2IVwUpdiPwV5-ldG8aV22tx4EMrl7So,3459
+microsoft_graph_helpers/core.py,sha256=O_jyONwqkGDvqeKrNEOaWF-g8da7YHuJ1NcHOv2Hsko,3075
+microsoft_graph_helpers/email.py,sha256=Bn1vtJVlgdsVNrRSap4BO3yQLnRyUvTjRCtKoVWRHM0,3512
+microsoft_graph_helpers/groups.py,sha256=7fVGKsMhrCy86HUMGTcVgGP-nS41vQYoxQhQkOMWDK4,1497
+microsoft_graph_helpers/security.py,sha256=ah4-ivoclOz2vRH4whAh5n-AZdqamwO8vouANRRQVW8,843
+microsoft_graph_helpers/users.py,sha256=rYYplRNKdIcZfpFjotoQ8AGR297e-RWDvSj3xvg4NPA,2997
+microsoft_graph_helpers-0.1.0.dist-info/METADATA,sha256=7bZAbuXCAI1ZD1c42BujBae3xvISfBqWlepFehXqLa0,596
+microsoft_graph_helpers-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_graph_helpers-0.1.0.dist-info/top_level.txt,sha256=A4584PIoEOJgkpiRByl6xTiRGNVE1onTOvKgHQbkMY8,24
+microsoft_graph_helpers-0.1.0.dist-info/RECORD,,

microsoft_graph_helpers-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_graph_helpers-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_graph_helpers