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

libre_devops_helpers/microsoft/resources.py

@@ -0,0 +1,137 @@
+"""The APIs this tool talks to, as a token sees them, and what features need from a token.
+
+A ``Resource`` is an API: the URL a token is requested for and the ``aud`` values that
+mean it. Resources are built per cloud. A ``Requirement`` is declared by a feature
+module (``entra``, ``xdr``, ...) to say which scopes or roles its calls need, so core
+checks tokens without knowing any feature.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from libre_devops_helpers.core.errors import LdoError
+from libre_devops_helpers.microsoft.clouds import PUBLIC, Cloud
+
+# First-party application ids. They are the same in every cloud, and a token may carry
+# one as its audience instead of the URL.
+GRAPH_APP_ID = "00000003-0000-0000-c000-000000000000"
+MDE_APP_ID = "fc780465-2017-40d4-a0c5-307022471b92"
+ARM_APP_ID = "797f4846-ba00-4fd7-ba43-dac1f8f63013"
+LOG_ANALYTICS_APP_ID = "ca7f3f0b-7d91-482c-8e09-c5d840d0eac5"
+KEY_VAULT_APP_ID = "cfa8b339-82a2-471a-a3c9-0fc0be7a4093"
+
+
+def normalise_audience(value: str) -> str:
+    """Compare audiences case-insensitively and without a trailing slash."""
+    return value.strip().rstrip("/").lower()
+
+
+@dataclass(frozen=True)
+class Resource:
+    """An API as seen by a token.
+
+    ``url`` is what is asked for when requesting a token. ``audiences`` are the ``aud``
+    claim values that mean this API (normalised).
+    """
+
+    key: str
+    url: str
+    audiences: frozenset[str]
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """What one feature needs from a token for the resource called ``resource``.
+
+    Every inner tuple of ``all_of`` must be satisfied, each by any one of its scopes or
+    roles: ``(("Device.Read.All", "Directory.Read.All"),)`` needs either of the two.
+    """
+
+    feature: str
+    resource: str
+    all_of: tuple[tuple[str, ...], ...]
+
+
+def _resource(key: str, url: str, *audiences: str, description: str) -> Resource:
+    return Resource(
+        key=key,
+        url=url,
+        audiences=frozenset(normalise_audience(value) for value in (url, *audiences)),
+        description=description,
+    )
+
+
+def resources_for(cloud: Cloud) -> dict[str, Resource]:
+    """Every API this tool can call in ``cloud``, keyed by resource key."""
+    found = [
+        _resource(
+            "graph",
+            cloud.graph_url,
+            GRAPH_APP_ID,
+            description="Microsoft Graph (Entra ID and Intune)",
+        ),
+        _resource(
+            "arm",
+            cloud.arm_url + "/",
+            cloud.arm_classic_url,
+            ARM_APP_ID,
+            description="Azure Resource Manager",
+        ),
+        _resource(
+            "loganalytics",
+            cloud.log_analytics_url,
+            LOG_ANALYTICS_APP_ID,
+            description="Log Analytics query API",
+        ),
+        _resource(
+            "keyvault",
+            f"https://{cloud.keyvault_suffix}",
+            KEY_VAULT_APP_ID,
+            description="Key Vault data plane",
+        ),
+    ]
+    if cloud.mde_url is not None:
+        found.append(
+            _resource(
+                "mde",
+                cloud.mde_url,
+                "https://securitycenter.onmicrosoft.com/windowsatpservice",
+                MDE_APP_ID,
+                description="Defender for Endpoint API",
+            )
+        )
+    return {resource.key: resource for resource in found}
+
+
+# The public cloud's resources, for callers that do not deal in clouds.
+RESOURCES: Mapping[str, Resource] = resources_for(PUBLIC)
+GRAPH = RESOURCES["graph"]
+MDE = RESOURCES["mde"]
+ARM = RESOURCES["arm"]
+LOG_ANALYTICS = RESOURCES["loganalytics"]
+KEY_VAULT = RESOURCES["keyvault"]
+
+
+def resolve_resource(value: str, cloud: Cloud = PUBLIC) -> Resource:
+    """Look up a resource by key (``graph``, ``mde``, ...) or by an https URL.
+
+    An unknown https URL is wrapped as an ad hoc resource whose only accepted audience
+    is the URL itself.
+    """
+    known = resources_for(cloud)
+    key = value.strip()
+    if key.lower() in known:
+        return known[key.lower()]
+    if key.startswith("https://"):
+        audience = normalise_audience(key)
+        for resource in known.values():
+            if audience in resource.audiences:
+                return resource
+        return Resource(key=key, url=key, audiences=frozenset({audience}))
+    raise LdoError(
+        f"unknown resource {value!r}",
+        hint=f"use one of {', '.join(sorted(known))}, or an https:// resource URL",
+    )

libre_devops_helpers/microsoft/tokens.py

@@ -0,0 +1,269 @@
+"""Decode an Entra ID access token and check it is the token you meant to get.
+
+Only the claims are inspected; the signature is NOT verified. The checks answer
+"is this token for the right API and tenant, in date, with the permissions this
+tool needs?", not "is this token genuine?". Microsoft Graph tokens cannot be
+signature-checked by a client in any case.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal
+
+from libre_devops_helpers.core.errors import TokenError
+from libre_devops_helpers.core.util import format_duration
+from libre_devops_helpers.microsoft.resources import (
+    Requirement,
+    Resource,
+    normalise_audience,
+)
+
+Status = Literal["pass", "warn", "fail"]
+
+
+@dataclass(frozen=True)
+class DecodedToken:
+    """The header and claims of a JWT, with accessors for the common claims."""
+
+    header: Mapping[str, Any]
+    claims: Mapping[str, Any]
+
+    def timestamp(self, claim: str) -> datetime | None:
+        """A NumericDate claim (``exp``, ``nbf``, ``iat``) as an aware UTC datetime."""
+        value = self.claims.get(claim)
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            return None
+        return datetime.fromtimestamp(value, UTC)
+
+    @property
+    def expires_at(self) -> datetime | None:
+        return self.timestamp("exp")
+
+    @property
+    def not_before(self) -> datetime | None:
+        return self.timestamp("nbf")
+
+    @property
+    def issued_at(self) -> datetime | None:
+        return self.timestamp("iat")
+
+    @property
+    def audiences(self) -> tuple[str, ...]:
+        aud = self.claims.get("aud")
+        if isinstance(aud, str):
+            return (aud,)
+        if isinstance(aud, list):
+            return tuple(str(item) for item in aud)
+        return ()
+
+    @property
+    def tenant_id(self) -> str:
+        return str(self.claims.get("tid", ""))
+
+    @property
+    def issuer(self) -> str:
+        return str(self.claims.get("iss", ""))
+
+    @property
+    def scopes(self) -> tuple[str, ...]:
+        """Delegated permissions (``scp``)."""
+        scp = self.claims.get("scp")
+        return tuple(scp.split()) if isinstance(scp, str) else ()
+
+    @property
+    def roles(self) -> tuple[str, ...]:
+        """Application permissions (``roles``)."""
+        roles = self.claims.get("roles")
+        return tuple(str(role) for role in roles) if isinstance(roles, list) else ()
+
+    @property
+    def principal(self) -> str:
+        """Who the token is for: a user name for delegated tokens, else an app id."""
+        for claim in ("upn", "unique_name", "preferred_username", "appid", "azp", "oid"):
+            value = self.claims.get(claim)
+            if isinstance(value, str) and value:
+                return value
+        return ""
+
+    @property
+    def app_id(self) -> str:
+        """The client application that requested the token."""
+        return str(self.claims.get("appid") or self.claims.get("azp") or "")
+
+    @property
+    def identity_type(self) -> str:
+        """``user`` (delegated), ``app`` (application), or ``unknown``."""
+        idtyp = self.claims.get("idtyp")
+        if isinstance(idtyp, str) and idtyp:
+            return idtyp
+        if self.scopes:
+            return "user"
+        return "app" if self.roles else "unknown"
+
+
+@dataclass(frozen=True)
+class Check:
+    """The outcome of one token check."""
+
+    name: str
+    status: Status
+    detail: str
+
+
+def decode_token(token: str) -> DecodedToken:
+    """Decode a JWT without verifying it. Accepts an optional ``Bearer`` prefix."""
+    raw = token.strip()
+    if raw[:7].lower() == "bearer ":
+        raw = raw[7:].strip()
+    parts = raw.split(".")
+    if len(parts) == 5:
+        raise TokenError("this is an encrypted token (JWE); its claims cannot be read")
+    if len(parts) != 3:
+        raise TokenError("not a JWT: expected three dot-separated parts")
+    return DecodedToken(header=_segment(parts[0], "header"), claims=_segment(parts[1], "payload"))
+
+
+def _segment(value: str, name: str) -> dict[str, Any]:
+    try:
+        data = json.loads(base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)))
+    except (binascii.Error, ValueError) as exc:
+        raise TokenError(f"cannot decode the token {name}: {exc}") from None
+    if not isinstance(data, dict):
+        raise TokenError(f"the token {name} is not a JSON object")
+    return data
+
+
+def validate_token(
+    token: DecodedToken,
+    *,
+    resource: Resource | None = None,
+    tenant_id: str | None = None,
+    required: Iterable[str] = (),
+    requirements: Iterable[Requirement] = (),
+    now: datetime | None = None,
+    clock_skew: timedelta = timedelta(minutes=1),
+    expiry_warning: timedelta = timedelta(minutes=5),
+) -> list[Check]:
+    """Check a decoded token's claims.
+
+    Always checks expiry, not-before and that the issuer matches the token's own
+    tenant. With ``resource`` it checks the audience, and warns for each of the
+    ``requirements`` for that resource the token does not cover (so it says which
+    features the token can serve). With ``tenant_id`` it checks the tenant. Each name
+    in ``required`` must appear in ``scp`` or ``roles``.
+    """
+    now = now or datetime.now(UTC)
+    checks: list[Check] = []
+
+    expires = token.expires_at
+    if expires is None:
+        checks.append(Check("expiry", "fail", "no exp claim"))
+    elif expires <= now:
+        checks.append(Check("expiry", "fail", f"expired {format_duration(now - expires)} ago"))
+    elif expires - now <= expiry_warning:
+        checks.append(Check("expiry", "warn", f"expires in {format_duration(expires - now)}"))
+    else:
+        checks.append(Check("expiry", "pass", f"expires in {format_duration(expires - now)}"))
+
+    not_before = token.not_before
+    if not_before is not None and not_before - now > clock_skew:
+        checks.append(
+            Check("not-before", "fail", f"not valid for {format_duration(not_before - now)}")
+        )
+
+    if token.tenant_id:
+        if token.tenant_id.lower() in token.issuer.lower():
+            checks.append(Check("issuer", "pass", token.issuer))
+        else:
+            checks.append(
+                Check("issuer", "fail", f"{token.issuer!r} does not match tid {token.tenant_id}")
+            )
+
+    if tenant_id is not None:
+        if token.tenant_id.lower() == tenant_id.lower():
+            checks.append(Check("tenant", "pass", token.tenant_id))
+        else:
+            checks.append(
+                Check("tenant", "fail", f"tid {token.tenant_id or '(none)'}, expected {tenant_id}")
+            )
+
+    if resource is not None:
+        checks.append(_audience_check(token, resource))
+
+    granted = {permission.casefold() for permission in (*token.scopes, *token.roles)}
+    if resource is not None:
+        relevant = [item for item in requirements if item.resource == resource.key]
+        checks.extend(_permission_checks(relevant, granted, {*token.scopes, *token.roles}))
+    for permission in required:
+        if permission.casefold() in granted:
+            checks.append(Check(f"requires {permission}", "pass", "present"))
+        else:
+            checks.append(Check(f"requires {permission}", "fail", "not in scp or roles"))
+
+    return checks
+
+
+def passed(checks: Iterable[Check], *, strict: bool = False) -> bool:
+    """True when no check failed (and, with ``strict``, none warned)."""
+    bad = {"fail", "warn"} if strict else {"fail"}
+    return not any(check.status in bad for check in checks)
+
+
+def _audience_check(token: DecodedToken, resource: Resource) -> Check:
+    audiences = token.audiences
+    if any(normalise_audience(aud) in resource.audiences for aud in audiences):
+        return Check("audience", "pass", f"{', '.join(audiences)} is {resource.key}")
+    return Check(
+        "audience",
+        "fail",
+        f"{', '.join(audiences) or '(none)'} is not {resource.key} ({resource.url})",
+    )
+
+
+def _permission_checks(
+    requirements: list[Requirement], granted: set[str], names: set[str]
+) -> list[Check]:
+    if not requirements:
+        return []
+    if not granted:
+        return [
+            Check(
+                "permissions",
+                "warn",
+                "no scp or roles claim; access then rests on the service's own RBAC",
+            )
+        ]
+    if granted == {"user_impersonation"}:
+        # A delegated grant with no granular scopes, as the Azure CLI gets for Defender:
+        # what the user can do is decided by their role in the service, not by the token.
+        return [
+            Check(
+                "permissions",
+                "warn",
+                "only user_impersonation; access then rests on your role in the service",
+            )
+        ]
+    by_name = {name.casefold(): name for name in names}
+    checks: list[Check] = []
+    for requirement in requirements:
+        via: list[str] = []
+        missing: list[tuple[str, ...]] = []
+        for group in requirement.all_of:
+            match = next((p for p in group if p.casefold() in granted), None)
+            if match is None:
+                missing.append(group)
+            else:
+                via.append(by_name.get(match.casefold(), match))
+        name = f"permissions: {requirement.feature}"
+        if missing:
+            needs = "; ".join("one of " + ", ".join(group) for group in missing)
+            checks.append(Check(name, "warn", f"needs {needs}"))
+        else:
+            checks.append(Check(name, "pass", "via " + ", ".join(dict.fromkeys(via))))
+    return checks

libre_devops_helpers/microsoft/xdr/__init__.py

@@ -0,0 +1,33 @@
+"""Defender for Endpoint (Defender XDR): machines, alerts, vulnerabilities, indicators, hunting.
+
+Depends only on ``core`` and the shared Microsoft layer. Public API::
+
+    from libre_devops_helpers.microsoft.auth import AzureCliCredential
+    from libre_devops_helpers.microsoft.xdr import XdrClient
+
+    with XdrClient.create(AzureCliCredential(), tenant_id) as xdr:
+        lookup = xdr.find_machine("web01.corp.example.com")
+        if lookup.machine:
+            print(lookup.machine.onboarding_status, lookup.machine.health_status)
+"""
+
+from libre_devops_helpers.microsoft.xdr.client import XdrClient, parse_severity
+from libre_devops_helpers.microsoft.xdr.models import (
+    Alert,
+    Indicator,
+    Machine,
+    MachineLookup,
+    Vulnerability,
+)
+from libre_devops_helpers.microsoft.xdr.permissions import REQUIREMENTS
+
+__all__ = [
+    "REQUIREMENTS",
+    "Alert",
+    "Indicator",
+    "Machine",
+    "MachineLookup",
+    "Vulnerability",
+    "XdrClient",
+    "parse_severity",
+]

libre_devops_helpers/microsoft/xdr/client.py

@@ -0,0 +1,246 @@
+"""Read-only Defender for Endpoint queries: machines, alerts, vulnerabilities, hunting.
+
+Device lookups are small, server-side filtered GETs per candidate name, never a
+download of the tenant-wide machine inventory. The FQDN is tried first, then the short
+hostname, because Defender does not report Linux names consistently.
+"""
+
+from __future__ import annotations
+
+import itertools
+import re
+from collections.abc import Iterable
+from datetime import UTC, datetime, timedelta
+from typing import Self
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import ApiError, LdoError, NotFoundError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.core.tables import QueryResult
+from libre_devops_helpers.core.util import (
+    candidate_names,
+    odata_datetime,
+    odata_string,
+)
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+from libre_devops_helpers.microsoft.xdr.models import (
+    Alert,
+    Indicator,
+    Machine,
+    MachineLookup,
+    Vulnerability,
+)
+
+_MACHINE_ID = re.compile(r"^[0-9a-fA-F]{40}$")
+_NEVER = datetime.min.replace(tzinfo=UTC)
+_SEVERITY_ORDER = {"informational": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
+
+# The global Defender resource; regional endpoints accept its tokens.
+MDE_RESOURCE = PUBLIC.mde_url or "https://api.securitycenter.microsoft.com"
+
+
+class XdrClient:
+    """Defender for Endpoint 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,
+        *,
+        api_url: str = MDE_RESOURCE,
+        resource: str = MDE_RESOURCE,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> XdrClient:
+        """A client for ``tenant_id``. ``api_url`` may be a regional Defender endpoint.
+
+        ``resource`` is what tokens are requested for: the cloud's Defender resource,
+        which regional endpoints accept too.
+        """
+        api = ApiClient(
+            api_url,
+            token_source(tokens, resource, tenant_id),
+            name="Defender for Endpoint",
+            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,
+    ) -> XdrClient:
+        """A client for a configured profile's tenant and Defender endpoint."""
+        resource = profile.cloud.require_mde()
+        return cls.create(
+            tokens,
+            profile.tenant_id,
+            api_url=profile.mde_url or resource,
+            resource=resource,
+            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()
+
+    # Machines ---------------------------------------------------------------------
+
+    def machines_named(self, name: str) -> list[Machine]:
+        """Every machine record whose ``computerDnsName`` equals ``name``."""
+        items = self.api.get_all(
+            "/api/machines", params={"$filter": f"computerDnsName eq {odata_string(name)}"}
+        )
+        return [Machine.from_json(item) for item in items]
+
+    def find_machine(self, name: str) -> MachineLookup:
+        """Look one device up by FQDN, falling back to its short hostname."""
+        for candidate in candidate_names(name):
+            records = self.machines_named(candidate)
+            if records:
+                newest_first = sorted(
+                    records, key=lambda machine: machine.last_seen or _NEVER, reverse=True
+                )
+                return MachineLookup(name, candidate, tuple(newest_first))
+        return MachineLookup(name, None)
+
+    def find_machines(self, names: Iterable[str]) -> list[MachineLookup]:
+        """``find_machine`` for each name, in order."""
+        return [self.find_machine(name) for name in names]
+
+    def get_machine(self, machine_id: str) -> Machine:
+        """One machine by its Defender id (40 hex characters)."""
+        machine_id = _machine_id(machine_id)
+        try:
+            return Machine.from_json(self.api.get(f"/api/machines/{machine_id}"))
+        except ApiError as exc:
+            if exc.status == 404:
+                raise NotFoundError(f"no MDE machine has id {machine_id}") from None
+            raise
+
+    def stale_machines(
+        self, older_than: timedelta, *, now: datetime | None = None
+    ) -> list[Machine]:
+        """Machines not seen for ``older_than``, longest silent first.
+
+        The filter runs on the server, so only the stale records are downloaded.
+        """
+        cutoff = (now or datetime.now(UTC)) - older_than
+        items = self.api.get_all(
+            "/api/machines", params={"$filter": f"lastSeen lt {odata_datetime(cutoff)}"}
+        )
+        machines = [Machine.from_json(item) for item in items]
+        return sorted(machines, key=lambda machine: machine.last_seen or _NEVER)
+
+    # Alerts -----------------------------------------------------------------------
+
+    def alerts(
+        self,
+        *,
+        machine_id: str | None = None,
+        since: datetime | None = None,
+        min_severity: str | None = None,
+        include_resolved: bool = False,
+        limit: int = 200,
+    ) -> list[Alert]:
+        """Alerts for the tenant, or for one machine, newest first.
+
+        The creation-time filter runs on the server; severity and status are filtered
+        here, because the API's support for filtering those varies by endpoint.
+        """
+        if machine_id is not None:
+            items = self.api.get_all(f"/api/machines/{_machine_id(machine_id)}/alerts")
+        else:
+            params = {"$top": str(max(1, min(limit, 10000)))}
+            if since is not None:
+                params["$filter"] = f"alertCreationTime ge {odata_datetime(since)}"
+            items = self.api.get_all("/api/alerts", params=params)
+        floor = parse_severity(min_severity) if min_severity else -1
+        alerts = [
+            alert
+            for alert in (Alert.from_json(item) for item in items)
+            if (include_resolved or not alert.resolved)
+            and _severity_rank(alert.severity) >= floor
+            and (since is None or alert.created is None or alert.created >= since)
+        ]
+        alerts.sort(key=lambda alert: alert.created or _NEVER, reverse=True)
+        return list(itertools.islice(alerts, limit))
+
+    # Vulnerabilities --------------------------------------------------------------
+
+    def vulnerabilities(self, machine_id: str) -> list[Vulnerability]:
+        """Vulnerabilities on one machine, most severe first."""
+        items = self.api.get_all(f"/api/machines/{_machine_id(machine_id)}/vulnerabilities")
+        found = [Vulnerability.from_json(item) for item in items]
+        return sorted(
+            found,
+            key=lambda item: (_severity_rank(item.severity), item.cvss or 0.0),
+            reverse=True,
+        )
+
+    # Indicators -------------------------------------------------------------------
+
+    def indicators(self) -> list[Indicator]:
+        """Every custom indicator in the tenant."""
+        return [Indicator.from_json(item) for item in self.api.get_all("/api/indicators")]
+
+    # Advanced Hunting -------------------------------------------------------------
+
+    def hunt(self, query: str) -> QueryResult:
+        """Run an Advanced Hunting (KQL) query. The API caps results at 100,000 rows."""
+        if not query.strip():
+            raise LdoError("the hunting query is empty")
+        data = self.api.post("/api/advancedqueries/run", {"Query": query})
+        schema = data.get("Schema")
+        results = data.get("Results")
+        columns = (
+            [str(column.get("Name")) for column in schema if isinstance(column, dict)]
+            if isinstance(schema, list)
+            else []
+        )
+        rows = (
+            [row for row in results if isinstance(row, dict)] if isinstance(results, list) else []
+        )
+        if not columns:
+            return QueryResult.from_records(rows)
+        return QueryResult(tuple(columns), tuple(rows))
+
+
+def parse_severity(severity: str) -> int:
+    """The rank of a severity someone typed. Raises for anything unknown."""
+    rank = _SEVERITY_ORDER.get(severity.strip().casefold())
+    if rank is None:
+        raise LdoError(
+            f"unknown severity {severity!r}", hint=f"use one of {', '.join(_SEVERITY_ORDER)}"
+        )
+    return rank
+
+
+def _severity_rank(severity: str | None) -> int:
+    # Values from the API are ranked leniently: an unknown one sorts below the rest.
+    return _SEVERITY_ORDER.get((severity or "").casefold(), -1)
+
+
+def _machine_id(value: str) -> str:
+    machine_id = value.strip()
+    if not _MACHINE_ID.match(machine_id):
+        raise LdoError(f"not an MDE machine id: {machine_id!r}")
+    return machine_id