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

libre_devops_helpers/microsoft/devices/check.py

@@ -0,0 +1,286 @@
+"""Check a list of devices against expectations, once (fast) or until done (watch).
+
+Speed comes from three things. Lookups for different devices run in parallel. Each
+expected group's members are fetched once per pass rather than once per device. And a
+watch rechecks only the devices not yet complete, unless asked to recheck them all.
+
+A rejected token or a missing permission (HTTP 401 or 403) ends the check, since every
+device would fail the same way. Anything else that fails for one device is recorded
+as an error for that device, and a watch simply tries again next pass.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from typing import TypeVar
+
+from libre_devops_helpers.core.auth import utc_now
+from libre_devops_helpers.core.errors import ApiError, LdoError, ReauthRequired
+from libre_devops_helpers.core.poll import PollLimits, PollOutcome, poll
+from libre_devops_helpers.microsoft.devices.models import (
+    CheckRun,
+    DeviceReport,
+    Expectations,
+    Outcome,
+)
+from libre_devops_helpers.microsoft.entra.client import EntraClient
+from libre_devops_helpers.microsoft.entra.models import EntraDevice
+from libre_devops_helpers.microsoft.intune.client import IntuneClient
+from libre_devops_helpers.microsoft.intune.models import ManagedDevice
+from libre_devops_helpers.microsoft.xdr.client import XdrClient
+from libre_devops_helpers.microsoft.xdr.models import MachineLookup
+
+_FATAL = frozenset({401, 403})
+
+T = TypeVar("T")
+
+
+class DeviceChecker:
+    """Checks devices against ``Expectations`` using whichever clients they need."""
+
+    def __init__(
+        self,
+        *,
+        entra: EntraClient | None = None,
+        xdr: XdrClient | None = None,
+        intune: IntuneClient | None = None,
+        workers: int = 8,
+        clock: Callable[[], datetime] = utc_now,
+    ) -> None:
+        if workers < 1:
+            raise LdoError("workers must be at least 1")
+        self._entra = entra
+        self._xdr = xdr
+        self._intune = intune
+        self._workers = workers
+        self._clock = clock
+
+    def check(self, names: Sequence[str], expectations: Expectations) -> CheckRun:
+        """One pass over ``names``, in order."""
+        self._require_clients(expectations)
+        self._prepare(expectations)
+        members = self._group_members(expectations.groups)
+        if not names:
+            return CheckRun((), self._clock(), 0)
+        try:
+            reports = self._check_all(names, expectations, members)
+        except ReauthRequired:
+            # A sign-in lapsed mid-pass, in a worker, which must not stop to ask anyone.
+            # Ask here on the calling thread (this raises again if nobody can sign in),
+            # then run the pass again.
+            self._prepare(expectations)
+            reports = self._check_all(names, expectations, members)
+        return CheckRun(tuple(reports), self._clock(), len(names))
+
+    def _prepare(self, expectations: Expectations) -> None:
+        """Get each service's token on this thread before the workers need it.
+
+        A token is normally cached already, so this is cheap; when a sign-in has lapsed,
+        it is where a credential that can ask someone to sign in again gets to ask.
+        """
+        for needed, client in (
+            (expectations.needs_entra or expectations.groups, self._entra),
+            (expectations.needs_defender, self._xdr),
+            (expectations.needs_intune, self._intune),
+        ):
+            if needed and client is not None:
+                client.api.ensure_token()
+
+    def _check_all(
+        self,
+        names: Sequence[str],
+        expectations: Expectations,
+        members: Mapping[str, frozenset[str]],
+    ) -> list[DeviceReport]:
+        with ThreadPoolExecutor(max_workers=min(self._workers, len(names))) as pool:
+            return list(pool.map(lambda name: self._check_one(name, expectations, members), names))
+
+    def _require_clients(self, expectations: Expectations) -> None:
+        missing = [
+            service
+            for service, needed, client in (
+                ("Entra", expectations.needs_entra, self._entra),
+                ("Defender", expectations.needs_defender, self._xdr),
+                ("Intune", expectations.needs_intune, self._intune),
+            )
+            if needed and client is None
+        ]
+        if missing:
+            raise LdoError(f"these checks need a client for {', '.join(missing)}")
+
+    def _group_members(self, groups: Sequence[str]) -> dict[str, frozenset[str]]:
+        if not groups or self._entra is None:
+            return {}
+        entra = self._entra
+        members: dict[str, frozenset[str]] = {}
+        for ref in groups:
+            group = entra.get_group(ref)
+            members[ref] = frozenset(device.id for device in entra.group_devices(group))
+        return members
+
+    def _check_one(
+        self, name: str, expectations: Expectations, members: Mapping[str, frozenset[str]]
+    ) -> DeviceReport:
+        errors: dict[str, str] = {}
+        entra_devices: tuple[EntraDevice, ...] = ()
+        lookup: MachineLookup | None = None
+        managed: tuple[ManagedDevice, ...] = ()
+        if expectations.needs_entra and self._entra is not None:
+            entra = self._entra
+            entra_devices = _guarded(errors, "entra", lambda: tuple(entra.find_devices(name)), ())
+        if expectations.needs_defender and self._xdr is not None:
+            xdr = self._xdr
+            lookup = _guarded(errors, "defender", lambda: xdr.find_machine(name), None)
+        if expectations.needs_intune and self._intune is not None:
+            intune = self._intune
+            managed = _guarded(errors, "intune", lambda: tuple(intune.find_devices(name)), ())
+
+        outcomes: list[Outcome] = []
+        if expectations.in_entra:
+            outcomes.append(_entra_outcome(entra_devices, errors.get("entra")))
+        machine = lookup.machine if lookup is not None else None
+        defender_error = errors.get("defender")
+        if expectations.onboarded:
+            if defender_error:
+                outcomes.append(Outcome("defender", "error", defender_error))
+            elif machine is None:
+                outcomes.append(Outcome("defender", "unmet", "no Defender record"))
+            elif machine.onboarding_status == "Onboarded":
+                outcomes.append(Outcome("defender", "met", f"onboarded, {machine.health_status}"))
+            else:
+                outcomes.append(
+                    Outcome("defender", "unmet", machine.onboarding_status or "not onboarded")
+                )
+        if expectations.active:
+            if defender_error:
+                outcomes.append(Outcome("active", "error", defender_error))
+            elif machine is None:
+                outcomes.append(Outcome("active", "unmet", "no Defender record"))
+            elif machine.health_status == "Active":
+                outcomes.append(Outcome("active", "met", "Active"))
+            else:
+                outcomes.append(Outcome("active", "unmet", machine.health_status or "unknown"))
+        for tag in expectations.tags:
+            check = f"tag {tag}"
+            if defender_error:
+                outcomes.append(Outcome(check, "error", defender_error))
+            elif machine is None:
+                outcomes.append(Outcome(check, "unmet", "no Defender record"))
+            elif tag.casefold() in {item.casefold() for item in machine.machine_tags}:
+                outcomes.append(Outcome(check, "met", "tagged"))
+            else:
+                outcomes.append(Outcome(check, "unmet", "tag missing"))
+        for device_group in expectations.device_groups:
+            check = f"device group {device_group}"
+            if defender_error:
+                outcomes.append(Outcome(check, "error", defender_error))
+            elif machine is None:
+                outcomes.append(Outcome(check, "unmet", "no Defender record"))
+            elif machine.device_group.casefold() == device_group.casefold():
+                outcomes.append(Outcome(check, "met", "in the device group"))
+            else:
+                outcomes.append(Outcome(check, "unmet", f"in {machine.device_group or 'none'}"))
+        for group in expectations.groups:
+            check = f"group {group}"
+            if errors.get("entra"):
+                outcomes.append(Outcome(check, "error", errors["entra"]))
+            elif not entra_devices:
+                outcomes.append(Outcome(check, "unmet", "not in Entra"))
+            elif any(device.id in members.get(group, frozenset()) for device in entra_devices):
+                outcomes.append(Outcome(check, "met", "member"))
+            else:
+                outcomes.append(Outcome(check, "unmet", "not a member"))
+        newest = managed[0] if managed else None
+        if expectations.in_intune:
+            if errors.get("intune"):
+                outcomes.append(Outcome("intune", "error", errors["intune"]))
+            elif newest is None:
+                outcomes.append(Outcome("intune", "unmet", "not enrolled in Intune"))
+            else:
+                outcomes.append(Outcome("intune", "met", newest.management_agent or "enrolled"))
+        if expectations.compliant:
+            if errors.get("intune"):
+                outcomes.append(Outcome("compliant", "error", errors["intune"]))
+            elif newest is None:
+                outcomes.append(Outcome("compliant", "unmet", "not enrolled in Intune"))
+            elif newest.compliant:
+                outcomes.append(Outcome("compliant", "met", "compliant"))
+            else:
+                outcomes.append(Outcome("compliant", "unmet", newest.compliance_state or "unknown"))
+        return DeviceReport(name, tuple(outcomes), entra_devices, lookup, managed)
+
+
+def watch(
+    checker: DeviceChecker,
+    names: Sequence[str],
+    expectations: Expectations,
+    limits: PollLimits,
+    *,
+    recheck: bool = False,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+    on_pass: Callable[[int, CheckRun], None] | None = None,
+    on_wait: Callable[[float], None] | None = None,
+) -> PollOutcome[CheckRun]:
+    """Check ``names`` every ``limits.interval`` until all are complete or a limit hits.
+
+    A device that met everything is not checked again unless ``recheck`` is set, so
+    later passes only cost calls for the devices still outstanding. A pass that fails
+    outright (other than on a rejected token) is reported and the next pass tries again.
+    """
+    latest: dict[str, DeviceReport] = {}
+    order = list(names)
+
+    def current(error: str | None = None) -> CheckRun:
+        reports = tuple(latest[name] for name in order if name in latest)
+        return CheckRun(reports, utc_now(), len(order), error)
+
+    def run_pass(_number: int) -> CheckRun:
+        pending = (
+            order
+            if recheck
+            else [name for name in order if name not in latest or not latest[name].complete]
+        )
+        try:
+            run = checker.check(pending, expectations)
+        except ApiError as exc:
+            if exc.status in _FATAL:
+                raise
+            return current(str(exc))
+        for report in run.reports:
+            latest[report.name] = report
+        return current()
+
+    return poll(
+        run_pass,
+        lambda run: run.complete,
+        limits,
+        clock=clock,
+        sleep=sleep,
+        on_pass=on_pass,
+        on_wait=on_wait,
+    )
+
+
+def _guarded(errors: dict[str, str], key: str, call: Callable[[], T], default: T) -> T:
+    try:
+        return call()
+    except ApiError as exc:
+        if exc.status in _FATAL:
+            raise
+        errors[key] = str(exc)
+        return default
+
+
+def _entra_outcome(devices: tuple[EntraDevice, ...], error: str | None) -> Outcome:
+    if error:
+        return Outcome("entra", "error", error)
+    if not devices:
+        return Outcome("entra", "unmet", "not in Entra")
+    if all(device.enabled is False for device in devices):
+        return Outcome("entra", "unmet", "disabled in Entra")
+    detail = "present" if len(devices) == 1 else f"{len(devices)} objects share the name"
+    return Outcome("entra", "met", detail)

libre_devops_helpers/microsoft/devices/inspect.py

@@ -0,0 +1,146 @@
+"""One device across Entra, Defender and Intune, and what looks wrong about it.
+
+Entra is required: it is where a device's identity lives. Defender and Intune are
+optional, and a failure reading either one (a suspended service, a token without the
+scope) becomes a finding rather than an error, so the rest of the picture still shows.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from libre_devops_helpers.core.auth import utc_now
+from libre_devops_helpers.core.errors import ApiError
+from libre_devops_helpers.core.util import format_duration
+from libre_devops_helpers.microsoft.devices.models import DeviceView, Finding
+from libre_devops_helpers.microsoft.entra.client import EntraClient
+from libre_devops_helpers.microsoft.entra.models import EntraDevice, EntraGroup
+from libre_devops_helpers.microsoft.intune.client import IntuneClient
+from libre_devops_helpers.microsoft.intune.models import ManagedDevice
+from libre_devops_helpers.microsoft.xdr.client import XdrClient
+from libre_devops_helpers.microsoft.xdr.models import MachineLookup
+
+
+def inspect_device(
+    name: str,
+    *,
+    entra: EntraClient,
+    xdr: XdrClient | None = None,
+    intune: IntuneClient | None = None,
+    stale_after: timedelta = timedelta(days=7),
+    now: datetime | None = None,
+) -> DeviceView:
+    """Everything the services know about ``name``, with findings worth acting on."""
+    now = now or utc_now()
+    findings: list[Finding] = []
+
+    devices = tuple(entra.find_devices(name))
+    groups: dict[str, tuple[EntraGroup, ...]] = {
+        device.id: tuple(entra.device_groups(device)) for device in devices
+    }
+    findings.extend(_entra_findings(devices))
+
+    lookup: MachineLookup | None = None
+    if xdr is not None:
+        try:
+            lookup = xdr.find_machine(name)
+        except ApiError as exc:
+            findings.append(Finding("warn", f"Defender could not be read: {exc}"))
+        else:
+            findings.extend(_defender_findings(lookup, devices, stale_after, now))
+
+    managed: tuple[ManagedDevice, ...] | None = None
+    if intune is not None:
+        try:
+            managed = tuple(intune.find_devices(name))
+        except ApiError as exc:
+            findings.append(Finding("warn", f"Intune could not be read: {exc}"))
+        else:
+            findings.extend(_intune_findings(managed, devices))
+
+    if not any(finding.level == "warn" for finding in findings):
+        findings.append(Finding("ok", "nothing looks wrong"))
+    return DeviceView(name, devices, groups, lookup, managed, tuple(findings))
+
+
+def _entra_findings(devices: tuple[EntraDevice, ...]) -> list[Finding]:
+    if not devices:
+        return [Finding("warn", "not in Entra")]
+    found: list[Finding] = []
+    if len(devices) > 1:
+        found.append(
+            Finding("warn", f"{len(devices)} Entra objects share this name (stale registrations)")
+        )
+    found.extend(
+        Finding("warn", f"Entra object {device.id} is disabled")
+        for device in devices
+        if device.enabled is False
+    )
+    return found
+
+
+def _defender_findings(
+    lookup: MachineLookup,
+    devices: tuple[EntraDevice, ...],
+    stale_after: timedelta,
+    now: datetime,
+) -> list[Finding]:
+    machine = lookup.machine
+    if machine is None:
+        return [Finding("warn", "no Defender record")]
+    found: list[Finding] = []
+    if len(lookup.records) > 1:
+        found.append(Finding("warn", f"{len(lookup.records)} Defender records; the newest is used"))
+    if lookup.matched_name != lookup.query.strip().rstrip("."):
+        found.append(Finding("info", f"Defender knows it by its short name {lookup.matched_name}"))
+    if machine.onboarding_status != "Onboarded":
+        found.append(
+            Finding("warn", f"Defender onboarding status is {machine.onboarding_status or '-'}")
+        )
+    if machine.health_status != "Active":
+        found.append(Finding("warn", f"Defender health is {machine.health_status or '-'}"))
+    if machine.last_seen is not None and now - machine.last_seen > stale_after:
+        found.append(
+            Finding("warn", f"Defender last saw it {format_duration(now - machine.last_seen)} ago")
+        )
+    if not machine.aad_device_id:
+        found.append(
+            Finding(
+                "info", "Defender has no Entra device id for it (not Entra joined or registered)"
+            )
+        )
+    elif devices and machine.aad_device_id.lower() not in {d.device_id.lower() for d in devices}:
+        found.append(
+            Finding(
+                "warn",
+                f"Defender links it to Entra device {machine.aad_device_id}, "
+                "which is not one of the Entra objects with this name",
+            )
+        )
+    return found
+
+
+def _intune_findings(
+    managed: tuple[ManagedDevice, ...], devices: tuple[EntraDevice, ...]
+) -> list[Finding]:
+    if not managed:
+        return [Finding("info", "not enrolled in Intune")]
+    newest = managed[0]
+    found: list[Finding] = []
+    if len(managed) > 1:
+        found.append(Finding("warn", f"{len(managed)} Intune records; the newest sync is used"))
+    if not newest.compliant:
+        found.append(Finding("warn", f"Intune compliance is {newest.compliance_state or '-'}"))
+    if (
+        newest.azure_ad_device_id
+        and devices
+        and newest.azure_ad_device_id.lower() not in {d.device_id.lower() for d in devices}
+    ):
+        found.append(
+            Finding(
+                "warn",
+                f"Intune links it to Entra device {newest.azure_ad_device_id}, "
+                "which is not one of the Entra objects with this name",
+            )
+        )
+    return found

libre_devops_helpers/microsoft/devices/models.py

@@ -0,0 +1,148 @@
+"""What a device check expects, and what it found."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+from libre_devops_helpers.core.errors import InputError
+from libre_devops_helpers.microsoft.entra.models import EntraDevice, EntraGroup
+from libre_devops_helpers.microsoft.intune.models import ManagedDevice
+from libre_devops_helpers.microsoft.xdr.models import MachineLookup
+
+Status = Literal["met", "unmet", "error"]
+Level = Literal["ok", "info", "warn"]
+
+
+@dataclass(frozen=True)
+class Expectations:
+    """The state every device should be in. Each enabled item is one check per device."""
+
+    in_entra: bool = True
+    onboarded: bool = True
+    active: bool = False
+    tags: tuple[str, ...] = ()
+    device_groups: tuple[str, ...] = ()
+    groups: tuple[str, ...] = ()
+    in_intune: bool = False
+    compliant: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.checks:
+            raise InputError(
+                "nothing to check",
+                hint="enable at least one of Entra, Defender, tags, device groups, groups",
+            )
+
+    @property
+    def needs_entra(self) -> bool:
+        return self.in_entra or bool(self.groups)
+
+    @property
+    def needs_defender(self) -> bool:
+        return self.onboarded or self.active or bool(self.tags) or bool(self.device_groups)
+
+    @property
+    def needs_intune(self) -> bool:
+        return self.in_intune or self.compliant
+
+    @property
+    def checks(self) -> tuple[str, ...]:
+        """The check names, in the order they are reported."""
+        names: list[str] = []
+        if self.in_entra:
+            names.append("entra")
+        if self.onboarded:
+            names.append("defender")
+        if self.active:
+            names.append("active")
+        names.extend(f"tag {tag}" for tag in self.tags)
+        names.extend(f"device group {group}" for group in self.device_groups)
+        names.extend(f"group {group}" for group in self.groups)
+        if self.in_intune:
+            names.append("intune")
+        if self.compliant:
+            names.append("compliant")
+        return tuple(names)
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """One check on one device."""
+
+    check: str
+    status: Status
+    detail: str
+
+
+@dataclass(frozen=True)
+class DeviceReport:
+    """Everything one check pass found for one device name."""
+
+    name: str
+    outcomes: tuple[Outcome, ...]
+    entra: tuple[EntraDevice, ...] = ()
+    defender: MachineLookup | None = None
+    intune: tuple[ManagedDevice, ...] = ()
+
+    @property
+    def complete(self) -> bool:
+        return all(outcome.status == "met" for outcome in self.outcomes)
+
+    def outcome(self, check: str) -> Outcome | None:
+        return next((item for item in self.outcomes if item.check == check), None)
+
+
+@dataclass(frozen=True)
+class CheckRun:
+    """One pass over every device. ``error`` is set when the pass itself failed."""
+
+    reports: tuple[DeviceReport, ...]
+    checked_at: datetime
+    expected: int
+    error: str | None = None
+
+    @property
+    def complete(self) -> bool:
+        return (
+            self.error is None
+            and len(self.reports) == self.expected
+            and all(report.complete for report in self.reports)
+        )
+
+    def counts(self, checks: tuple[str, ...]) -> dict[str, int]:
+        """How many devices meet each check."""
+        return {
+            check: sum(
+                1
+                for report in self.reports
+                if (outcome := report.outcome(check)) is not None and outcome.status == "met"
+            )
+            for check in checks
+        }
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One observation about a device from ``devices show``."""
+
+    level: Level
+    message: str
+
+
+@dataclass(frozen=True)
+class DeviceView:
+    """A device across Entra, Defender and Intune, with what looks wrong about it.
+
+    ``defender`` and ``intune`` are None when that service was not asked, or could not
+    be read (a finding says which).
+    """
+
+    name: str
+    entra: tuple[EntraDevice, ...]
+    groups: Mapping[str, tuple[EntraGroup, ...]] = field(default_factory=dict)
+    defender: MachineLookup | None = None
+    intune: tuple[ManagedDevice, ...] | None = None
+    findings: tuple[Finding, ...] = ()

libre_devops_helpers/microsoft/entra/__init__.py

@@ -0,0 +1,41 @@
+"""Entra ID through Microsoft Graph: devices, users, groups, roles, sign-ins, apps and policies.
+
+Depends only on ``core`` and the shared Microsoft layer. Public API::
+
+    from libre_devops_helpers.microsoft.auth import AzureCliCredential
+    from libre_devops_helpers.microsoft.entra import EntraClient
+
+    with EntraClient.create(AzureCliCredential(), tenant_id) as entra:
+        for device in entra.find_devices("web01.corp.example.com"):
+            groups = entra.device_groups(device)
+"""
+
+from libre_devops_helpers.microsoft.entra.client import EntraClient, MemberKind, expiring
+from libre_devops_helpers.microsoft.entra.models import (
+    AppCredential,
+    ConditionalAccessPolicy,
+    DirectoryObject,
+    EntraDevice,
+    EntraGroup,
+    EntraUser,
+    RoleAssignment,
+    RoleReport,
+    SignIn,
+)
+from libre_devops_helpers.microsoft.entra.permissions import REQUIREMENTS
+
+__all__ = [
+    "REQUIREMENTS",
+    "AppCredential",
+    "ConditionalAccessPolicy",
+    "DirectoryObject",
+    "EntraClient",
+    "EntraDevice",
+    "EntraGroup",
+    "EntraUser",
+    "MemberKind",
+    "RoleAssignment",
+    "RoleReport",
+    "SignIn",
+    "expiring",
+]