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

libre_devops_helpers/microsoft/azure/client.py

@@ -0,0 +1,260 @@
+"""Read-only Azure Resource Manager queries.
+
+Subscriptions, Azure Resource Graph, RBAC role assignments, and Defender for Cloud
+(secure score, controls, recommendations, plans). Access rests on Azure RBAC (Reader is
+enough for all of it), not on token scopes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Self
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import ApiError, LdoError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.core.tables import QueryResult
+from libre_devops_helpers.core.util import is_guid
+from libre_devops_helpers.microsoft.azure.models import (
+    Assessment,
+    AzureRoleAssignment,
+    DefenderPlan,
+    SecureScore,
+    SecureScoreControl,
+    Subscription,
+)
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+
+SUBSCRIPTIONS_API = "2022-12-01"
+RESOURCE_GRAPH_API = "2022-10-01"
+AUTHORIZATION_API = "2022-04-01"
+SECURE_SCORE_API = "2020-01-01"
+ASSESSMENTS_API = "2021-06-01"
+PRICINGS_API = "2024-01-01"
+
+# Resource Graph returns at most 1000 rows a page.
+_GRAPH_PAGE = 1000
+
+
+class AzureClient:
+    """Azure Resource Manager lookups. Close it (or use ``with``) when done."""
+
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+        self._role_names: dict[str, str] = {}
+
+    @classmethod
+    def create(
+        cls,
+        tokens: TokenProvider,
+        tenant_id: str,
+        *,
+        arm_url: str = PUBLIC.arm_url,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> AzureClient:
+        """A client for ``tenant_id`` that takes its ARM tokens from ``tokens``."""
+        api = ApiClient(
+            arm_url,
+            token_source(tokens, arm_url.rstrip("/") + "/", tenant_id),
+            name="Azure Resource Manager",
+            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,
+    ) -> AzureClient:
+        """A client for a configured profile's tenant, in the profile's cloud."""
+        return cls.create(
+            tokens, profile.tenant_id, arm_url=profile.cloud.arm_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()
+
+    # Subscriptions ----------------------------------------------------------------
+
+    def subscriptions(self, tenant_id: str | None = None) -> list[Subscription]:
+        """Subscriptions the credential can see, in ``tenant_id`` when given, by name."""
+        items = self.api.get_all(
+            "/subscriptions", params={"api-version": SUBSCRIPTIONS_API}, next_link="nextLink"
+        )
+        found = [Subscription.from_json(item) for item in items]
+        if tenant_id is not None:
+            found = [item for item in found if item.tenant_id == tenant_id.lower()]
+        return sorted(found, key=lambda item: item.name.casefold())
+
+    # Resource Graph ---------------------------------------------------------------
+
+    def resource_graph(
+        self, query: str, *, subscriptions: Iterable[str] = (), limit: int = 1000
+    ) -> QueryResult:
+        """Run an Azure Resource Graph (KQL) query, following ``$skipToken`` up to ``limit``.
+
+        Without ``subscriptions`` the query covers every subscription the credential can
+        read in the tenant.
+        """
+        if not query.strip():
+            raise LdoError("the Resource Graph query is empty")
+        scope = [_subscription_id(item) for item in subscriptions]
+        rows: list[dict[str, Any]] = []
+        skip_token: str | None = None
+        truncated = False
+        while True:
+            options: dict[str, Any] = {
+                "resultFormat": "objectArray",
+                "$top": min(_GRAPH_PAGE, limit - len(rows)),
+            }
+            if skip_token:
+                options["$skipToken"] = skip_token
+            body: dict[str, Any] = {"query": query, "options": options}
+            if scope:
+                body["subscriptions"] = scope
+            page = self.api.post(
+                "/providers/Microsoft.ResourceGraph/resources",
+                body,
+                params={"api-version": RESOURCE_GRAPH_API},
+            )
+            data = page.get("data")
+            if isinstance(data, list):
+                rows.extend(row for row in data if isinstance(row, dict))
+            token = page.get("$skipToken")
+            skip_token = token if isinstance(token, str) and token else None
+            if skip_token is None:
+                break
+            if len(rows) >= limit:
+                truncated = True
+                break
+        return QueryResult.from_records(rows, truncated=truncated)
+
+    # RBAC -------------------------------------------------------------------------
+
+    def role_assignments(
+        self, principal_id: str, subscription_ids: Iterable[str]
+    ) -> list[AzureRoleAssignment]:
+        """Every role assignment that applies to ``principal_id`` in the subscriptions.
+
+        ``assignedTo()`` includes assignments made to groups the principal belongs to,
+        and those inherited from management groups above each subscription.
+        """
+        principal_id = _guid(principal_id, "principal id")
+        seen: dict[str, AzureRoleAssignment] = {}
+        for subscription_id in subscription_ids:
+            items = self.api.get_all(
+                f"/subscriptions/{_subscription_id(subscription_id)}"
+                "/providers/Microsoft.Authorization/roleAssignments",
+                params={
+                    "api-version": AUTHORIZATION_API,
+                    "$filter": f"assignedTo('{principal_id}')",
+                },
+                next_link="nextLink",
+            )
+            for item in items:
+                assignment_id = str(item.get("id") or "")
+                if assignment_id and assignment_id not in seen:
+                    properties = item.get("properties")
+                    definition = (
+                        str(properties.get("roleDefinitionId") or "")
+                        if isinstance(properties, dict)
+                        else ""
+                    )
+                    seen[assignment_id] = AzureRoleAssignment.from_json(
+                        item, self._role_name(definition)
+                    )
+        return sorted(seen.values(), key=lambda item: (item.scope.casefold(), item.role_name))
+
+    def _role_name(self, definition_id: str) -> str:
+        if not definition_id:
+            return ""
+        if definition_id not in self._role_names:
+            try:
+                data = self.api.get(definition_id, params={"api-version": AUTHORIZATION_API})
+                properties = data.get("properties")
+                name = str(properties.get("roleName") or "") if isinstance(properties, dict) else ""
+            except ApiError:
+                # The assignment is still worth showing without a friendly name.
+                name = ""
+            self._role_names[definition_id] = name or definition_id.rsplit("/", 1)[-1]
+        return self._role_names[definition_id]
+
+    # Defender for Cloud -----------------------------------------------------------
+
+    def secure_score(self, subscription_id: str) -> SecureScore | None:
+        """The subscription's secure score, or None where Defender for Cloud has none."""
+        subscription_id = _subscription_id(subscription_id)
+        try:
+            data = self.api.get(
+                f"/subscriptions/{subscription_id}/providers/Microsoft.Security/secureScores/ascScore",
+                params={"api-version": SECURE_SCORE_API},
+            )
+        except ApiError as exc:
+            if exc.status == 404:
+                return None
+            raise
+        return SecureScore.from_json(subscription_id, data)
+
+    def secure_score_controls(self, subscription_id: str) -> list[SecureScoreControl]:
+        """Security controls, the ones costing the most points first."""
+        items = self.api.get_all(
+            f"/subscriptions/{_subscription_id(subscription_id)}"
+            "/providers/Microsoft.Security/secureScoreControls",
+            params={"api-version": SECURE_SCORE_API, "$expand": "definition"},
+            next_link="nextLink",
+        )
+        controls = [SecureScoreControl.from_json(item) for item in items]
+        return sorted(controls, key=lambda control: control.points_lost, reverse=True)
+
+    def assessments(self, subscription_id: str, *, unhealthy_only: bool = True) -> list[Assessment]:
+        """Defender for Cloud recommendation results, most severe first."""
+        items = self.api.get_all(
+            f"/subscriptions/{_subscription_id(subscription_id)}"
+            "/providers/Microsoft.Security/assessments",
+            params={"api-version": ASSESSMENTS_API, "$expand": "metadata"},
+            next_link="nextLink",
+        )
+        found = [Assessment.from_json(item) for item in items]
+        if unhealthy_only:
+            found = [item for item in found if item.unhealthy]
+        order = {"high": 0, "medium": 1, "low": 2}
+        return sorted(found, key=lambda item: (order.get(item.severity.casefold(), 3), item.name))
+
+    def defender_plans(self, subscription_id: str) -> list[DefenderPlan]:
+        """Every Defender for Cloud plan on the subscription and its tier."""
+        data = self.api.get(
+            f"/subscriptions/{_subscription_id(subscription_id)}/providers/Microsoft.Security/pricings",
+            params={"api-version": PRICINGS_API},
+        )
+        items = data.get("value")
+        plans = [
+            DefenderPlan.from_json(item)
+            for item in (items if isinstance(items, list) else [])
+            if isinstance(item, dict)
+        ]
+        return sorted(plans, key=lambda plan: plan.name.casefold())
+
+
+def _guid(value: str, what: str) -> str:
+    if not is_guid(value):
+        raise LdoError(f"not a {what}: {value!r}")
+    return value.strip().lower()
+
+
+def _subscription_id(value: str) -> str:
+    return _guid(value, "subscription id")

libre_devops_helpers/microsoft/azure/models.py

@@ -0,0 +1,198 @@
+"""Azure Resource Manager records, 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
+
+from libre_devops_helpers.core.util import parse_datetime
+
+
+def _map(value: object) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _text(data: Mapping[str, Any], key: str) -> str:
+    return str(data.get(key) or "")
+
+
+def _number(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    return float(value)
+
+
+@dataclass(frozen=True)
+class Subscription:
+    """An Azure subscription the credential can see."""
+
+    id: str
+    name: str
+    state: str
+    tenant_id: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> Subscription:
+        return cls(
+            id=_text(data, "subscriptionId").lower(),
+            name=_text(data, "displayName"),
+            state=_text(data, "state"),
+            tenant_id=_text(data, "tenantId").lower(),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class AzureRoleAssignment:
+    """An Azure RBAC role assignment. ``role_name`` is resolved from the definition."""
+
+    id: str
+    scope: str
+    role_name: str
+    role_definition_id: str
+    principal_id: str
+    principal_type: str
+    condition: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any], role_name: str) -> AzureRoleAssignment:
+        properties = _map(data.get("properties"))
+        return cls(
+            id=_text(data, "id"),
+            scope=_text(properties, "scope"),
+            role_name=role_name,
+            role_definition_id=_text(properties, "roleDefinitionId"),
+            principal_id=_text(properties, "principalId"),
+            principal_type=_text(properties, "principalType"),
+            condition=_text(properties, "condition"),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class SecureScore:
+    """A subscription's Defender for Cloud secure score."""
+
+    subscription_id: str
+    current: float | None
+    max: float | None
+    percentage: float | None
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, subscription_id: str, data: Mapping[str, Any]) -> SecureScore:
+        score = _map(_map(data.get("properties")).get("score"))
+        return cls(
+            subscription_id=subscription_id,
+            current=_number(score.get("current")),
+            max=_number(score.get("max")),
+            percentage=_number(score.get("percentage")),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class SecureScoreControl:
+    """One security control and how much of the secure score it is costing."""
+
+    name: str
+    current: float | None
+    max: float | None
+    percentage: float | None
+    healthy: int
+    unhealthy: int
+    not_applicable: int
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def points_lost(self) -> float:
+        return (self.max or 0.0) - (self.current or 0.0)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> SecureScoreControl:
+        properties = _map(data.get("properties"))
+        score = _map(properties.get("score"))
+
+        def count(key: str) -> int:
+            value = properties.get(key)
+            return value if isinstance(value, int) and not isinstance(value, bool) else 0
+
+        return cls(
+            name=_text(properties, "displayName") or _text(data, "name"),
+            current=_number(score.get("current")),
+            max=_number(score.get("max")),
+            percentage=_number(score.get("percentage")),
+            healthy=count("healthyResourceCount"),
+            unhealthy=count("unhealthyResourceCount"),
+            not_applicable=count("notApplicableResourceCount"),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class Assessment:
+    """A Defender for Cloud recommendation's result for one resource."""
+
+    id: str
+    name: str
+    status: str
+    severity: str
+    resource_id: str
+    cause: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def unhealthy(self) -> bool:
+        return self.status.casefold() == "unhealthy"
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> Assessment:
+        properties = _map(data.get("properties"))
+        status = _map(properties.get("status"))
+        metadata = _map(properties.get("metadata"))
+        assessment_id = _text(data, "id")
+        # The assessment id is the resource id with the assessment appended.
+        resource_id = assessment_id.split("/providers/Microsoft.Security/assessments/", 1)[0]
+        return cls(
+            id=assessment_id,
+            name=_text(properties, "displayName") or _text(data, "name"),
+            status=_text(status, "code"),
+            severity=_text(metadata, "severity"),
+            resource_id=resource_id,
+            cause=_text(status, "cause") or _text(status, "description"),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class DefenderPlan:
+    """A Defender for Cloud plan and whether it is on (Standard) or off (Free)."""
+
+    name: str
+    pricing_tier: str
+    sub_plan: str
+    trial_remaining: str
+    enabled_since: datetime | None
+    deprecated: bool
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def enabled(self) -> bool:
+        return self.pricing_tier.casefold() == "standard"
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> DefenderPlan:
+        properties = _map(data.get("properties"))
+        return cls(
+            name=_text(data, "name"),
+            pricing_tier=_text(properties, "pricingTier"),
+            sub_plan=_text(properties, "subPlan"),
+            trial_remaining=_text(properties, "freeTrialRemainingTime"),
+            enabled_since=parse_datetime(properties.get("enablementTime")),
+            deprecated=properties.get("deprecated") is True,
+            raw=dict(data),
+        )

libre_devops_helpers/microsoft/clouds.py

@@ -0,0 +1,83 @@
+"""Microsoft cloud environments and the endpoints each one uses.
+
+A profile names its cloud (``public`` unless set), and every client takes its base URL
+and token resource from here, so nothing else in the package hard-codes a host. The
+Azure CLI must be pointed at the same cloud (``az cloud set``) for its tokens to work.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from libre_devops_helpers.core.errors import ConfigError
+
+
+@dataclass(frozen=True)
+class Cloud:
+    """The endpoints of one Microsoft cloud. ``mde_url`` is None where Defender is absent."""
+
+    name: str
+    description: str
+    login_url: str
+    graph_url: str
+    arm_url: str
+    # The older ARM audience that some tokens still carry.
+    arm_classic_url: str
+    mde_url: str | None
+    log_analytics_url: str
+    keyvault_suffix: str
+
+    def require_mde(self) -> str:
+        """The Defender for Endpoint API URL, or ConfigError where this cloud has none."""
+        if self.mde_url is None:
+            raise ConfigError(f"Defender for Endpoint is not available in the {self.name} cloud")
+        return self.mde_url
+
+
+PUBLIC = Cloud(
+    name="public",
+    description="Azure public cloud",
+    login_url="https://login.microsoftonline.com",
+    graph_url="https://graph.microsoft.com",
+    arm_url="https://management.azure.com",
+    arm_classic_url="https://management.core.windows.net",
+    mde_url="https://api.securitycenter.microsoft.com",
+    log_analytics_url="https://api.loganalytics.io",
+    keyvault_suffix="vault.azure.net",
+)
+
+USGOV = Cloud(
+    name="usgov",
+    description="Azure US Government (GCC High)",
+    login_url="https://login.microsoftonline.us",
+    graph_url="https://graph.microsoft.us",
+    arm_url="https://management.usgovcloudapi.net",
+    arm_classic_url="https://management.core.usgovcloudapi.net",
+    mde_url="https://api-gov.securitycenter.microsoft.us",
+    log_analytics_url="https://api.loganalytics.us",
+    keyvault_suffix="vault.usgovcloudapi.net",
+)
+
+CHINA = Cloud(
+    name="china",
+    description="Azure operated by 21Vianet",
+    login_url="https://login.chinacloudapi.cn",
+    graph_url="https://microsoftgraph.chinacloudapi.cn",
+    arm_url="https://management.chinacloudapi.cn",
+    arm_classic_url="https://management.core.chinacloudapi.cn",
+    mde_url=None,
+    log_analytics_url="https://api.loganalytics.azure.cn",
+    keyvault_suffix="vault.azure.cn",
+)
+
+CLOUDS: dict[str, Cloud] = {cloud.name: cloud for cloud in (PUBLIC, USGOV, CHINA)}
+
+
+def get_cloud(name: str) -> Cloud:
+    """A cloud by name. Raises ConfigError listing the known names when absent."""
+    try:
+        return CLOUDS[name.strip().lower()]
+    except KeyError:
+        raise ConfigError(
+            f"unknown cloud {name!r}", hint=f"use one of {', '.join(CLOUDS)}"
+        ) from None