libre-devops-helpers 0.4.1__py3-none-any.whl

libre_devops_helpers/microsoft/incidents/models.py

@@ -0,0 +1,165 @@
+"""Defender XDR incidents and their alerts, as the Graph security API returns them.
+
+In the unified security operations platform, one incident queue holds Defender's own
+incidents and those from Microsoft Sentinel. Each alert names the service that raised
+it (``serviceSource``), which is how an incident is known to come from Sentinel.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from libre_devops_helpers.core.util import parse_datetime
+
+# Graph's serviceSource values, and a short name for each.
+SOURCES = {
+    "microsoftDefenderForEndpoint": "Endpoint",
+    "microsoftDefenderForIdentity": "Identity",
+    "microsoftDefenderForCloudApps": "Cloud Apps",
+    "microsoftDefenderForOffice365": "Office 365",
+    "microsoft365Defender": "XDR",
+    "azureAdIdentityProtection": "Entra ID Protection",
+    "microsoftAppGovernance": "App Governance",
+    "dataLossPrevention": "DLP",
+    "microsoftDefenderForCloud": "Defender for Cloud",
+    "microsoftSentinel": "Sentinel",
+    "microsoftInsiderRiskManagement": "Insider Risk",
+}
+# Most severe first; unknown values rank below informational.
+SEVERITY_ORDER = ("high", "medium", "low", "informational")
+# Graph's status values; "open" means any of the first three.
+OPEN_STATUSES = ("active", "inProgress", "awaitingAction")
+STATUSES = (*OPEN_STATUSES, "resolved", "redirected")
+
+
+def severity_rank(severity: str) -> int:
+    """0 for high, up to 4 for unknown: sort ascending for most severe first."""
+    try:
+        return SEVERITY_ORDER.index(severity.lower())
+    except ValueError:
+        return len(SEVERITY_ORDER)
+
+
+def _text(record: Mapping[str, Any], key: str) -> str:
+    value = record.get(key)
+    return "" if value is None else str(value)
+
+
+def _when(record: Mapping[str, Any], key: str) -> datetime | None:
+    return parse_datetime(record.get(key))
+
+
+@dataclass(frozen=True)
+class IncidentAlert:
+    """One alert in an incident."""
+
+    id: str
+    title: str
+    severity: str
+    status: str
+    source: str  # Graph's serviceSource
+    detection_source: str
+    created: datetime | None
+    devices: tuple[str, ...] = ()
+    users: tuple[str, ...] = ()
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def source_name(self) -> str:
+        return SOURCES.get(self.source, self.source or "unknown")
+
+    @classmethod
+    def from_graph(cls, record: Mapping[str, Any]) -> IncidentAlert:
+        devices: list[str] = []
+        users: list[str] = []
+        for evidence in record.get("evidence") or ():
+            if not isinstance(evidence, Mapping):
+                continue
+            kind = str(evidence.get("@odata.type", ""))
+            if kind.endswith("deviceEvidence"):
+                name = evidence.get("deviceDnsName") or evidence.get("hostName")
+                if name:
+                    devices.append(str(name))
+            elif kind.endswith("userEvidence"):
+                account = evidence.get("userAccount") or {}
+                name = account.get("userPrincipalName") or account.get("accountName")
+                if name:
+                    users.append(str(name))
+        return cls(
+            id=_text(record, "id"),
+            title=_text(record, "title"),
+            severity=_text(record, "severity"),
+            status=_text(record, "status"),
+            source=_text(record, "serviceSource"),
+            detection_source=_text(record, "detectionSource"),
+            created=_when(record, "createdDateTime"),
+            devices=tuple(dict.fromkeys(devices)),
+            users=tuple(dict.fromkeys(users)),
+            raw=dict(record),
+        )
+
+
+@dataclass(frozen=True)
+class Incident:
+    """One incident, with its alerts."""
+
+    id: str
+    title: str
+    severity: str
+    status: str
+    created: datetime | None
+    updated: datetime | None
+    assigned_to: str
+    classification: str
+    determination: str
+    web_url: str
+    tags: tuple[str, ...]
+    alerts: tuple[IncidentAlert, ...]
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def open(self) -> bool:
+        return self.status in OPEN_STATUSES
+
+    @property
+    def sources(self) -> tuple[str, ...]:
+        """The services that raised its alerts (Graph values), in first-seen order."""
+        return tuple(dict.fromkeys(alert.source for alert in self.alerts if alert.source))
+
+    @property
+    def source_names(self) -> tuple[str, ...]:
+        return tuple(SOURCES.get(source, source) for source in self.sources)
+
+    @property
+    def devices(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(name for alert in self.alerts for name in alert.devices))
+
+    @property
+    def users(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(name for alert in self.alerts for name in alert.users))
+
+    @classmethod
+    def from_graph(cls, record: Mapping[str, Any]) -> Incident:
+        tags = [*(record.get("customTags") or ()), *(record.get("systemTags") or ())]
+        return cls(
+            id=_text(record, "id"),
+            title=_text(record, "displayName"),
+            severity=_text(record, "severity"),
+            status=_text(record, "status"),
+            created=_when(record, "createdDateTime"),
+            updated=_when(record, "lastUpdateDateTime"),
+            assigned_to=_text(record, "assignedTo"),
+            classification=_text(record, "classification"),
+            determination=_text(record, "determination"),
+            web_url=_text(record, "incidentWebUrl"),
+            tags=tuple(str(tag) for tag in tags),
+            alerts=tuple(
+                IncidentAlert.from_graph(alert)
+                for alert in record.get("alerts") or ()
+                if isinstance(alert, Mapping)
+            ),
+            raw=dict(record),
+        )

libre_devops_helpers/microsoft/incidents/permissions.py

@@ -0,0 +1,15 @@
+"""What the incidents feature needs from a Graph token.
+
+The Azure CLI's Graph token never carries these, so incidents need an interactive or
+device-code profile whose app registration has been granted them.
+"""
+
+from libre_devops_helpers.microsoft.resources import Requirement
+
+REQUIREMENTS = (
+    Requirement(
+        "xdr incidents",
+        "graph",
+        (("SecurityIncident.Read.All", "SecurityIncident.ReadWrite.All"),),
+    ),
+)

libre_devops_helpers/microsoft/intune/__init__.py

@@ -0,0 +1,18 @@
+"""Intune through Microsoft Graph: managed devices and their compliance.
+
+Depends only on ``core`` and the shared Microsoft layer. The Azure CLI's Graph token
+cannot read Intune, so this needs a profile whose credential has
+``DeviceManagementManagedDevices.Read.All``. Public API::
+
+    from libre_devops_helpers.microsoft.intune import IntuneClient
+
+    with IntuneClient.for_profile(profile, tokens) as intune:
+        for device in intune.find_devices("laptop-042"):
+            print(device.device_name, device.compliance_state)
+"""
+
+from libre_devops_helpers.microsoft.intune.client import IntuneClient
+from libre_devops_helpers.microsoft.intune.models import ManagedDevice
+from libre_devops_helpers.microsoft.intune.permissions import REQUIREMENTS
+
+__all__ = ["REQUIREMENTS", "IntuneClient", "ManagedDevice"]

libre_devops_helpers/microsoft/intune/client.py

@@ -0,0 +1,94 @@
+"""Read-only Intune managed device queries through Microsoft Graph v1.0."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Self
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import LdoError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.core.util import candidate_names, is_guid, odata_string
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+from libre_devops_helpers.microsoft.intune.models import ManagedDevice
+
+_PATH = "/v1.0/deviceManagement/managedDevices"
+_NEVER = datetime.min.replace(tzinfo=UTC)
+
+
+class IntuneClient:
+    """Intune managed device lookups. Close it (or use ``with``) when done."""
+
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+
+    @classmethod
+    def create(
+        cls,
+        tokens: TokenProvider,
+        tenant_id: str,
+        *,
+        graph_url: str = PUBLIC.graph_url,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> IntuneClient:
+        """A client for ``tenant_id`` that takes its Graph tokens from ``tokens``."""
+        api = ApiClient(
+            graph_url,
+            token_source(tokens, graph_url, tenant_id),
+            name="Intune (Microsoft Graph)",
+            verify=verify,
+            session=session,
+        )
+        return cls(api)
+
+    @classmethod
+    def for_profile(
+        cls,
+        profile: Profile,
+        tokens: TokenProvider,
+        *,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> IntuneClient:
+        """A client for a configured profile's tenant, in the profile's cloud."""
+        return cls.create(
+            tokens,
+            profile.tenant_id,
+            graph_url=profile.cloud.graph_url,
+            verify=verify,
+            session=session,
+        )
+
+    def close(self) -> None:
+        self.api.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def find_devices(self, name: str) -> list[ManagedDevice]:
+        """Managed devices named ``name``, else its short hostname, newest sync first."""
+        for candidate in candidate_names(name):
+            found = self._query(f"deviceName eq {odata_string(candidate)}")
+            if found:
+                return found
+        return []
+
+    def for_entra_device(self, device_id: str) -> list[ManagedDevice]:
+        """Managed devices linked to an Entra ``deviceId`` (not its object id)."""
+        if not is_guid(device_id):
+            raise LdoError(f"not an Entra device id: {device_id!r}")
+        return self._query(f"azureADDeviceId eq {odata_string(device_id.strip())}")
+
+    def _query(self, expression: str) -> list[ManagedDevice]:
+        items = self.api.get_all(
+            _PATH, params={"$filter": expression, "$select": ManagedDevice.SELECT}
+        )
+        devices = [ManagedDevice.from_json(item) for item in items]
+        return sorted(devices, key=lambda device: device.last_sync or _NEVER, reverse=True)

libre_devops_helpers/microsoft/intune/models.py

@@ -0,0 +1,63 @@
+"""Intune managed devices as returned by Microsoft Graph, trimmed to the fields used here."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, ClassVar
+
+from libre_devops_helpers.core.util import parse_datetime
+
+
+@dataclass(frozen=True)
+class ManagedDevice:
+    """An Intune managed device. ``azure_ad_device_id`` links it to the Entra device."""
+
+    SELECT: ClassVar[str] = (
+        "id,deviceName,operatingSystem,osVersion,complianceState,managementAgent,"
+        "lastSyncDateTime,enrolledDateTime,azureADDeviceId,userPrincipalName,"
+        "serialNumber,managedDeviceOwnerType"
+    )
+
+    id: str
+    device_name: str
+    operating_system: str
+    os_version: str
+    compliance_state: str
+    management_agent: str
+    last_sync: datetime | None
+    enrolled: datetime | None
+    azure_ad_device_id: str
+    user_principal_name: str
+    serial_number: str
+    owner_type: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def compliant(self) -> bool:
+        return self.compliance_state.casefold() == "compliant"
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> ManagedDevice:
+        def text(key: str) -> str:
+            return str(data.get(key) or "")
+
+        return cls(
+            id=text("id"),
+            device_name=text("deviceName"),
+            operating_system=text("operatingSystem"),
+            os_version=text("osVersion"),
+            compliance_state=text("complianceState"),
+            management_agent=text("managementAgent"),
+            last_sync=parse_datetime(data.get("lastSyncDateTime")),
+            enrolled=parse_datetime(data.get("enrolledDateTime")),
+            # Intune reports an unlinked device with the all-zero GUID.
+            azure_ad_device_id=""
+            if text("azureADDeviceId") == "00000000-0000-0000-0000-000000000000"
+            else text("azureADDeviceId"),
+            user_principal_name=text("userPrincipalName"),
+            serial_number=text("serialNumber"),
+            owner_type=text("managedDeviceOwnerType"),
+            raw=dict(data),
+        )

libre_devops_helpers/microsoft/intune/permissions.py

@@ -0,0 +1,16 @@
+"""What the Intune feature needs from a Graph token. The Azure CLI's token has neither."""
+
+from libre_devops_helpers.microsoft.resources import Requirement
+
+REQUIREMENTS = (
+    Requirement(
+        "intune devices",
+        "graph",
+        (
+            (
+                "DeviceManagementManagedDevices.Read.All",
+                "DeviceManagementManagedDevices.ReadWrite.All",
+            ),
+        ),
+    ),
+)

libre_devops_helpers/microsoft/keyvault/__init__.py

@@ -0,0 +1,34 @@
+"""Key Vault: secret, certificate and key metadata for expiry checks. Never reads values.
+
+Depends only on ``core`` and the shared Microsoft layer. Access rests on Key Vault
+data-plane RBAC or access policies, so there are no token scope requirements to declare.
+Finding vaults across subscriptions is Resource Graph's job (``azure``); this module
+takes vault names. Public API::
+
+    from libre_devops_helpers.microsoft.keyvault import KeyVaultClient, expiring
+
+    with KeyVaultClient.for_profile(profile, tokens, "kv-app-prd") as vault:
+        soon = expiring(vault.items(), timedelta(days=30), now=datetime.now(UTC))
+"""
+
+from libre_devops_helpers.microsoft.keyvault.client import (
+    KINDS,
+    ItemKind,
+    KeyVaultClient,
+    VaultItem,
+    expiring,
+    vault_url,
+)
+from libre_devops_helpers.microsoft.resources import Requirement
+
+REQUIREMENTS: tuple[Requirement, ...] = ()
+
+__all__ = [
+    "KINDS",
+    "REQUIREMENTS",
+    "ItemKind",
+    "KeyVaultClient",
+    "VaultItem",
+    "expiring",
+    "vault_url",
+]

libre_devops_helpers/microsoft/keyvault/client.py

@@ -0,0 +1,185 @@
+"""Key Vault secret, certificate and key metadata, for expiry checks.
+
+Only list operations are used, and they return attributes (dates, enabled, content
+type) but never a secret value. Reading them needs a data-plane role such as Key Vault
+Reader, or a list permission in an access policy.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal, Self
+from urllib.parse import urlsplit
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import LdoError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.microsoft.clouds import PUBLIC, Cloud
+from libre_devops_helpers.microsoft.config import Profile
+
+API_VERSION = "7.4"
+_VAULT_NAME = re.compile(r"^[a-zA-Z][a-zA-Z0-9-]{1,22}[a-zA-Z0-9]$")
+
+ItemKind = Literal["secret", "certificate", "key"]
+KINDS: tuple[ItemKind, ...] = ("secret", "certificate", "key")
+
+
+def vault_url(vault: str, cloud: Cloud = PUBLIC) -> str:
+    """The data-plane URL for a vault given by name or by URL, checked against the cloud.
+
+    A URL must be on the cloud's Key Vault domain, so a token is never sent elsewhere.
+    """
+    value = vault.strip()
+    if "://" in value:
+        parts = urlsplit(value)
+        host = (parts.hostname or "").lower()
+        if parts.scheme != "https" or not host.endswith("." + cloud.keyvault_suffix):
+            raise LdoError(
+                f"{vault!r} is not a Key Vault URL in the {cloud.name} cloud",
+                hint=f"expected https://<name>.{cloud.keyvault_suffix}",
+            )
+        return f"https://{host}"
+    if not _VAULT_NAME.match(value):
+        raise LdoError(f"not a Key Vault name: {vault!r}")
+    return f"https://{value.lower()}.{cloud.keyvault_suffix}"
+
+
+@dataclass(frozen=True)
+class VaultItem:
+    """One secret, certificate or key, by its attributes. Never holds a value."""
+
+    vault: str
+    kind: ItemKind
+    name: str
+    enabled: bool | None
+    expires: datetime | None
+    not_before: datetime | None
+    updated: datetime | None
+    content_type: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    def days_left(self, now: datetime) -> int | None:
+        """Whole days until expiry (negative once expired), or None with no expiry set."""
+        return None if self.expires is None else (self.expires - now).days
+
+    @classmethod
+    def from_json(cls, vault: str, kind: ItemKind, data: Mapping[str, Any]) -> VaultItem:
+        attributes = data.get("attributes")
+        attributes = attributes if isinstance(attributes, Mapping) else {}
+        identifier = str(data.get("kid") or data.get("id") or "")
+        enabled = attributes.get("enabled")
+        return cls(
+            vault=vault,
+            kind=kind,
+            name=identifier.rstrip("/").rsplit("/", 1)[-1],
+            enabled=enabled if isinstance(enabled, bool) else None,
+            expires=_epoch(attributes.get("exp")),
+            not_before=_epoch(attributes.get("nbf")),
+            updated=_epoch(attributes.get("updated")),
+            content_type=str(data.get("contentType") or ""),
+            raw=dict(data),
+        )
+
+
+class KeyVaultClient:
+    """Metadata listing for one vault. Close it (or use ``with``) when done."""
+
+    def __init__(self, api: ApiClient, vault: str) -> None:
+        self.api = api
+        self.vault = vault
+
+    @classmethod
+    def create(
+        cls,
+        tokens: TokenProvider,
+        tenant_id: str,
+        vault: str,
+        *,
+        cloud: Cloud = PUBLIC,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> KeyVaultClient:
+        """A client for one vault (a name or URL) in ``tenant_id``."""
+        url = vault_url(vault, cloud)
+        api = ApiClient(
+            url,
+            token_source(tokens, f"https://{cloud.keyvault_suffix}", tenant_id),
+            name=f"Key Vault {urlsplit(url).hostname}",
+            verify=verify,
+            session=session,
+        )
+        return cls(api, (urlsplit(url).hostname or "").split(".", 1)[0])
+
+    @classmethod
+    def for_profile(
+        cls,
+        profile: Profile,
+        tokens: TokenProvider,
+        vault: str,
+        *,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> KeyVaultClient:
+        """A client for one vault in a configured profile's tenant and cloud."""
+        return cls.create(
+            tokens, profile.tenant_id, vault, cloud=profile.cloud, verify=verify, session=session
+        )
+
+    def close(self) -> None:
+        self.api.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def items(self, kinds: Iterable[ItemKind] = KINDS) -> list[VaultItem]:
+        """Secrets, certificates and keys in the vault, by kind then name.
+
+        A certificate's backing secret and key are ``managed`` and left out, so each
+        certificate is listed once.
+        """
+        found: list[VaultItem] = []
+        for kind in kinds:
+            for item in self.api.get_all(
+                f"/{kind}s", params={"api-version": API_VERSION}, next_link="nextLink"
+            ):
+                if item.get("managed") is True:
+                    continue
+                found.append(VaultItem.from_json(self.vault, kind, item))
+        return sorted(found, key=lambda item: (KINDS.index(item.kind), item.name.casefold()))
+
+
+def expiring(
+    items: Iterable[VaultItem],
+    within: timedelta,
+    *,
+    now: datetime,
+    include_expired: bool = True,
+    include_disabled: bool = False,
+) -> list[VaultItem]:
+    """Items that expire within ``within`` of ``now`` (and expired ones), soonest first.
+
+    Disabled items are left out unless asked for: nothing can use them anyway.
+    """
+    selected = [
+        item
+        for item in items
+        if item.expires is not None
+        and item.expires - now <= within
+        and (include_expired or item.expires >= now)
+        and (include_disabled or item.enabled is not False)
+    ]
+    return sorted(selected, key=lambda item: item.expires or now)
+
+
+def _epoch(value: object) -> datetime | None:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    return datetime.fromtimestamp(value, UTC)

libre_devops_helpers/microsoft/loganalytics/__init__.py

@@ -0,0 +1,17 @@
+"""Log Analytics: run KQL against a workspace (Sentinel workspaces included).
+
+Depends only on ``core`` and the shared Microsoft layer. Access rests on Azure RBAC on
+the workspace, so there are no token scope requirements to declare. Public API::
+
+    from libre_devops_helpers.microsoft.loganalytics import LogAnalyticsClient
+
+    with LogAnalyticsClient.for_profile(profile, tokens) as logs:
+        result = logs.query(workspace_id, "Heartbeat | summarize count() by Computer")
+"""
+
+from libre_devops_helpers.microsoft.loganalytics.client import LogAnalyticsClient
+from libre_devops_helpers.microsoft.resources import Requirement
+
+REQUIREMENTS: tuple[Requirement, ...] = ()
+
+__all__ = ["REQUIREMENTS", "LogAnalyticsClient"]