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

libre_devops_helpers/microsoft/pim/entra.py

@@ -0,0 +1,294 @@
+"""PIM for Entra roles and for groups, through Microsoft Graph v1.0.
+
+"Mine" views use Graph's ``filterByCurrentUser``, so they need a delegated token (the
+Azure CLI's does not carry the scopes; a profile with ``auth = "interactive"`` or
+``"device-code"`` does). A named principal is asked with a ``principalId`` filter, which
+an app registration's application permissions can serve. Graph asks for a ReadWrite
+scope even to list requests; this module still only ever reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+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, NotFoundError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.core.util import is_guid, odata_string, parse_datetime
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+from libre_devops_helpers.microsoft.pim.models import (
+    Area,
+    PimAssignment,
+    PimRequest,
+    PimSettings,
+)
+from libre_devops_helpers.microsoft.pim.rules import settings_from_rules
+
+_ROLES = "/v1.0/roleManagement/directory"
+_GROUPS = "/v1.0/identityGovernance/privilegedAccess/group"
+
+
+class GraphPimClient:
+    """PIM for Entra roles and PIM for Groups. Close it (or use ``with``) when done."""
+
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+        self._role_names: dict[str, str] | None = None
+        self._group_names: dict[str, str] = {}
+
+    @classmethod
+    def create(
+        cls,
+        tokens: TokenProvider,
+        tenant_id: str,
+        *,
+        graph_url: str = PUBLIC.graph_url,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> GraphPimClient:
+        api = ApiClient(
+            graph_url,
+            token_source(tokens, graph_url, tenant_id),
+            name="Graph PIM",
+            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,
+    ) -> GraphPimClient:
+        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()
+
+    # Entra roles --------------------------------------------------------------------
+
+    def role_eligible(self, *, principal_id: str | None = None) -> list[PimAssignment]:
+        items = self._mine_or_theirs(f"{_ROLES}/roleEligibilityScheduleInstances", principal_id)
+        return self._role_assignments(items, "eligible")
+
+    def role_active(self, *, principal_id: str | None = None) -> list[PimAssignment]:
+        items = self._mine_or_theirs(f"{_ROLES}/roleAssignmentScheduleInstances", principal_id)
+        return self._role_assignments(items, "active")
+
+    def role_requests(
+        self, *, approver: bool = False, principal_id: str | None = None
+    ) -> list[PimRequest]:
+        path = f"{_ROLES}/roleAssignmentScheduleRequests"
+        items = self._mine_or_theirs(path, principal_id, on="approver" if approver else "principal")
+        names = self.role_names()
+        return _newest([_request("entra", item, names) for item in items])
+
+    def role_settings(self, role: str) -> PimSettings:
+        """An Entra role's PIM settings, for the whole directory."""
+        role_id = self._role_id(role)
+        assignments = list(
+            self.api.get_all(
+                "/v1.0/policies/roleManagementPolicyAssignments",
+                params={
+                    "$filter": "scopeId eq '/' and scopeType eq 'DirectoryRole' "
+                    f"and roleDefinitionId eq {odata_string(role_id)}",
+                    "$expand": "policy($expand=rules)",
+                },
+            )
+        )
+        if not assignments:
+            raise NotFoundError(f"no PIM settings for the Entra role {role!r}")
+        return settings_from_rules(
+            "entra", self.role_names().get(role_id, role), "/", _rules(assignments[0])
+        )
+
+    def role_names(self) -> dict[str, str]:
+        """Every directory role definition's name by id, fetched once."""
+        if self._role_names is None:
+            self._role_names = {
+                str(item.get("id")): str(item.get("displayName") or "")
+                for item in self.api.get_all(
+                    f"{_ROLES}/roleDefinitions", params={"$select": "id,displayName"}
+                )
+            }
+        return self._role_names
+
+    # PIM for Groups -----------------------------------------------------------------
+
+    def group_eligible(self, *, principal_id: str | None = None) -> list[PimAssignment]:
+        items = self._mine_or_theirs(f"{_GROUPS}/eligibilityScheduleInstances", principal_id)
+        return self._group_assignments(items, "eligible")
+
+    def group_active(self, *, principal_id: str | None = None) -> list[PimAssignment]:
+        items = self._mine_or_theirs(f"{_GROUPS}/assignmentScheduleInstances", principal_id)
+        return self._group_assignments(items, "active")
+
+    def group_requests(
+        self, *, approver: bool = False, principal_id: str | None = None
+    ) -> list[PimRequest]:
+        path = f"{_GROUPS}/assignmentScheduleRequests"
+        items = self._mine_or_theirs(path, principal_id, on="approver" if approver else "principal")
+        return _newest([self._group_request(item) for item in items])
+
+    def group_settings(self, group_id: str, access: str = "member") -> PimSettings:
+        """A group's PIM settings for its members (``member``) or owners (``owner``)."""
+        group_id = _guid(group_id)
+        assignments = list(
+            self.api.get_all(
+                "/v1.0/policies/roleManagementPolicyAssignments",
+                params={
+                    "$filter": f"scopeId eq {odata_string(group_id)} and scopeType eq 'Group' "
+                    f"and roleDefinitionId eq {odata_string(access)}",
+                    "$expand": "policy($expand=rules)",
+                },
+            )
+        )
+        if not assignments:
+            raise NotFoundError(f"no PIM settings for group {group_id} ({access})")
+        return settings_from_rules(
+            "groups", access, self.group_name(group_id), _rules(assignments[0])
+        )
+
+    def group_name(self, group_id: str) -> str:
+        """A group's display name, cached; its id when the name cannot be read."""
+        if not is_guid(group_id):
+            # Never build a path from something that is not an object id.
+            return group_id
+        if group_id not in self._group_names:
+            try:
+                data = self.api.get(f"/v1.0/groups/{group_id}", params={"$select": "displayName"})
+                self._group_names[group_id] = str(data.get("displayName") or group_id)
+            except ApiError:
+                self._group_names[group_id] = group_id
+        return self._group_names[group_id]
+
+    # Helpers ------------------------------------------------------------------------
+
+    def _mine_or_theirs(
+        self, path: str, principal_id: str | None, *, on: str = "principal"
+    ) -> list[dict[str, Any]]:
+        if principal_id:
+            params = {"$filter": f"principalId eq {odata_string(_guid(principal_id))}"}
+            return list(self.api.get_all(path, params=params))
+        return list(self.api.get_all(f"{path}/filterByCurrentUser(on='{on}')"))
+
+    def _role_id(self, role: str) -> str:
+        if is_guid(role):
+            return role.strip().lower()
+        wanted = role.strip().casefold()
+        for role_id, name in self.role_names().items():
+            if name.casefold() == wanted:
+                return role_id
+        raise NotFoundError(f"no Entra role is named {role!r}")
+
+    def _role_assignments(self, items: list[dict[str, Any]], state: str) -> list[PimAssignment]:
+        names = self.role_names()
+        found = [
+            PimAssignment(
+                area="entra",
+                state="eligible" if state == "eligible" else "active",
+                role=names.get(
+                    str(item.get("roleDefinitionId")), str(item.get("roleDefinitionId") or "")
+                ),
+                scope=str(item.get("directoryScopeId") or "/"),
+                principal_id=str(item.get("principalId") or ""),
+                principal_name="",
+                member_type=str(item.get("memberType") or ""),
+                assignment_type=str(item.get("assignmentType") or ""),
+                starts=parse_datetime(item.get("startDateTime")),
+                ends=parse_datetime(item.get("endDateTime")),
+                raw=dict(item),
+            )
+            for item in items
+        ]
+        return sorted(found, key=lambda item: item.role.casefold())
+
+    def _group_assignments(self, items: list[dict[str, Any]], state: str) -> list[PimAssignment]:
+        found = [
+            PimAssignment(
+                area="groups",
+                state="eligible" if state == "eligible" else "active",
+                role=str(item.get("accessId") or ""),
+                scope=self.group_name(str(item.get("groupId") or "")),
+                principal_id=str(item.get("principalId") or ""),
+                principal_name="",
+                member_type=str(item.get("memberType") or ""),
+                assignment_type=str(item.get("assignmentType") or ""),
+                starts=parse_datetime(item.get("startDateTime")),
+                ends=parse_datetime(item.get("endDateTime")),
+                raw=dict(item),
+            )
+            for item in items
+        ]
+        return sorted(found, key=lambda item: (item.scope.casefold(), item.role))
+
+    def _group_request(self, item: Mapping[str, Any]) -> PimRequest:
+        return replace(
+            _request("groups", item, {}),
+            role=str(item.get("accessId") or ""),
+            scope=self.group_name(str(item.get("groupId") or "")),
+        )
+
+
+def _request(area: Area, item: Mapping[str, Any], role_names: Mapping[str, str]) -> PimRequest:
+    schedule = item.get("scheduleInfo")
+    schedule = schedule if isinstance(schedule, Mapping) else {}
+    expiration = schedule.get("expiration")
+    expiration = expiration if isinstance(expiration, Mapping) else {}
+    ticket = item.get("ticketInfo")
+    ticket = ticket if isinstance(ticket, Mapping) else {}
+    role_id = str(item.get("roleDefinitionId") or "")
+    return PimRequest(
+        area=area,
+        id=str(item.get("id") or ""),
+        action=str(item.get("action") or ""),
+        status=str(item.get("status") or ""),
+        role=role_names.get(role_id, role_id),
+        scope=str(item.get("directoryScopeId") or "/"),
+        principal_id=str(item.get("principalId") or ""),
+        principal_name="",
+        justification=str(item.get("justification") or ""),
+        created=parse_datetime(item.get("createdDateTime")),
+        starts=parse_datetime(schedule.get("startDateTime")),
+        ends=parse_datetime(expiration.get("endDateTime")),
+        duration=str(expiration.get("duration") or ""),
+        ticket=str(ticket.get("ticketNumber") or ""),
+        raw=dict(item),
+    )
+
+
+def _rules(assignment: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    policy = assignment.get("policy")
+    rules = policy.get("rules") if isinstance(policy, Mapping) else None
+    return [rule for rule in rules if isinstance(rule, Mapping)] if isinstance(rules, list) else []
+
+
+def _newest(requests_: list[PimRequest]) -> list[PimRequest]:
+    return sorted(requests_, key=lambda item: str(item.created or ""), reverse=True)
+
+
+def _guid(value: str) -> str:
+    if not is_guid(value):
+        raise LdoError(f"not an object id: {value!r}")
+    return value.strip().lower()

libre_devops_helpers/microsoft/pim/models.py

@@ -0,0 +1,93 @@
+"""PIM records, in one shape across Azure resources, Entra roles and PIM for Groups.
+
+Each API names things its own way (ARM's ``properties``, Graph's ``roleDefinitionId`` or
+``groupId`` and ``accessId``); the clients convert their replies into these, so the CLI
+shows all three areas in one table.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+Area = Literal["azure", "entra", "groups"]
+AREAS: tuple[Area, ...] = ("azure", "entra", "groups")
+
+
+@dataclass(frozen=True)
+class PimAssignment:
+    """A role someone is eligible for, or holds now.
+
+    ``role`` is the role's name (for PIM for Groups, ``member`` or ``owner`` of the group).
+    ``scope`` is where it applies: an ARM scope, a directory scope, or the group.
+    ``member_type`` is ``Direct``, ``Group`` (through a group) or ``Inherited`` (from a
+    scope above). ``assignment_type`` is ``Activated`` (through PIM) or ``Assigned``
+    (standing) for active roles, and empty for eligible ones.
+    """
+
+    area: Area
+    state: Literal["eligible", "active"]
+    role: str
+    scope: str
+    principal_id: str
+    principal_name: str
+    member_type: str
+    assignment_type: str
+    starts: datetime | None
+    ends: datetime | None
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def permanent(self) -> bool:
+        """True when nothing ends it: standing access, the thing PIM exists to reduce."""
+        return self.ends is None
+
+    @property
+    def activated(self) -> bool:
+        return self.assignment_type.casefold() == "activated"
+
+
+@dataclass(frozen=True)
+class PimRequest:
+    """A request to activate, assign or remove a role, and where it has got to."""
+
+    area: Area
+    id: str
+    action: str
+    status: str
+    role: str
+    scope: str
+    principal_id: str
+    principal_name: str
+    justification: str
+    created: datetime | None
+    starts: datetime | None
+    ends: datetime | None
+    duration: str
+    ticket: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @property
+    def pending(self) -> bool:
+        return self.status.casefold() == "pendingapproval"
+
+
+@dataclass(frozen=True)
+class PimSettings:
+    """A role's PIM settings: what activating it takes, and how long it lasts."""
+
+    area: Area
+    role: str
+    scope: str
+    max_activation: str
+    requires_mfa: bool
+    requires_justification: bool
+    requires_ticket: bool
+    requires_approval: bool
+    approvers: tuple[str, ...]
+    authentication_context: str
+    eligible_expiry: str
+    active_expiry: str
+    raw: tuple[Mapping[str, Any], ...] = field(default=(), compare=False, repr=False)

libre_devops_helpers/microsoft/pim/permissions.py

@@ -0,0 +1,98 @@
+"""What each PIM feature needs from a Graph token, as Graph itself reports it.
+
+Graph asks for a ReadWrite scope even to list requests. PIM for Azure resources goes
+through ARM and rests on Azure RBAC instead, so it has no requirements here.
+"""
+
+from libre_devops_helpers.microsoft.resources import Requirement
+
+_ROLE_MANAGEMENT = (
+    "RoleManagement.Read.Directory",
+    "RoleManagement.Read.All",
+    "RoleManagement.ReadWrite.Directory",
+)
+
+REQUIREMENTS = (
+    Requirement(
+        "pim entra eligible",
+        "graph",
+        (
+            (
+                "RoleEligibilitySchedule.Read.Directory",
+                "RoleEligibilitySchedule.ReadWrite.Directory",
+                *_ROLE_MANAGEMENT,
+            ),
+        ),
+    ),
+    Requirement(
+        "pim entra active",
+        "graph",
+        (
+            (
+                "RoleAssignmentSchedule.Read.Directory",
+                "RoleAssignmentSchedule.ReadWrite.Directory",
+                *_ROLE_MANAGEMENT,
+            ),
+        ),
+    ),
+    Requirement(
+        "pim entra requests",
+        "graph",
+        (("RoleAssignmentSchedule.ReadWrite.Directory", "RoleManagement.ReadWrite.Directory"),),
+    ),
+    Requirement(
+        "pim entra settings",
+        "graph",
+        (
+            (
+                "RoleManagementPolicy.Read.Directory",
+                "RoleManagementPolicy.ReadWrite.Directory",
+                *_ROLE_MANAGEMENT,
+            ),
+        ),
+    ),
+    Requirement(
+        "pim groups eligible",
+        "graph",
+        (
+            (
+                "PrivilegedEligibilitySchedule.Read.AzureADGroup",
+                "PrivilegedEligibilitySchedule.ReadWrite.AzureADGroup",
+                "PrivilegedAccess.Read.AzureADGroup",
+                "PrivilegedAccess.ReadWrite.AzureADGroup",
+            ),
+        ),
+    ),
+    Requirement(
+        "pim groups active",
+        "graph",
+        (
+            (
+                "PrivilegedAssignmentSchedule.Read.AzureADGroup",
+                "PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup",
+                "PrivilegedAccess.Read.AzureADGroup",
+                "PrivilegedAccess.ReadWrite.AzureADGroup",
+            ),
+        ),
+    ),
+    Requirement(
+        "pim groups requests",
+        "graph",
+        (
+            (
+                "PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup",
+                "PrivilegedAccess.ReadWrite.AzureADGroup",
+            ),
+        ),
+    ),
+    Requirement(
+        "pim groups settings",
+        "graph",
+        (
+            (
+                "RoleManagementPolicy.Read.AzureADGroup",
+                "RoleManagementPolicy.ReadWrite.AzureADGroup",
+            ),
+        ),
+    ),
+)

libre_devops_helpers/microsoft/pim/rules.py

@@ -0,0 +1,70 @@
+"""Read a PIM role management policy's rules into ``PimSettings``.
+
+Azure resources (ARM ``effectiveRules``) and Graph (``policy.rules``) use the same rule
+ids, such as ``Expiration_EndUser_Assignment`` for how long an activation may last, so
+one reader serves all three areas.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from libre_devops_helpers.microsoft.pim.models import Area, PimSettings
+
+
+def settings_from_rules(
+    area: Area, role: str, scope: str, rules: Iterable[Mapping[str, Any]]
+) -> PimSettings:
+    by_id = {str(rule.get("id") or ""): rule for rule in rules if isinstance(rule, Mapping)}
+    activation = by_id.get("Expiration_EndUser_Assignment", {})
+    enablement = by_id.get("Enablement_EndUser_Assignment", {})
+    approval = by_id.get("Approval_EndUser_Assignment", {})
+    context = by_id.get("AuthenticationContext_EndUser_Assignment", {})
+    enabled = {str(item).casefold() for item in enablement.get("enabledRules") or []}
+    setting = approval.get("setting") if isinstance(approval.get("setting"), Mapping) else {}
+    return PimSettings(
+        area=area,
+        role=role,
+        scope=scope,
+        max_activation=str(activation.get("maximumDuration") or ""),
+        requires_mfa="multifactorauthentication" in enabled,
+        requires_justification="justification" in enabled,
+        requires_ticket="ticketing" in enabled,
+        requires_approval=setting.get("isApprovalRequired") is True,
+        approvers=tuple(_approvers(setting)),
+        authentication_context=str(context.get("claimValue") or "")
+        if context.get("isEnabled") is True
+        else "",
+        eligible_expiry=_expiry(by_id.get("Expiration_Admin_Eligibility", {})),
+        active_expiry=_expiry(by_id.get("Expiration_Admin_Assignment", {})),
+        raw=tuple(by_id.values()),
+    )
+
+
+def _approvers(setting: Mapping[str, Any]) -> list[str]:
+    found: list[str] = []
+    for stage in setting.get("approvalStages") or []:
+        if not isinstance(stage, Mapping):
+            continue
+        for approver in stage.get("primaryApprovers") or []:
+            if isinstance(approver, Mapping):
+                found.append(
+                    str(
+                        approver.get("description")
+                        or approver.get("userId")
+                        or approver.get("groupId")
+                        or approver.get("id")
+                        or ""
+                    )
+                )
+    return [name for name in found if name]
+
+
+def _expiry(rule: Mapping[str, Any]) -> str:
+    """``permanent allowed``, the maximum duration, or empty when the rule is absent."""
+    if not rule:
+        return ""
+    if rule.get("isExpirationRequired") is False:
+        return "permanent allowed"
+    return str(rule.get("maximumDuration") or "required")

libre_devops_helpers/microsoft/process.py

@@ -0,0 +1,70 @@
+"""The Azure CLI as a subprocess: JSON output and ``az``'s own error shapes and hints.
+
+Shared by ``microsoft.auth.AzureCliCredential`` (tokens) and ``microsoft.azcli``
+(accounts and context switching). The subprocess handling itself is core's
+``CommandRunner``; this adds what is particular to ``az``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from libre_devops_helpers.core.errors import CommandError
+from libre_devops_helpers.core.process import CommandRunner, Runner
+
+# az prefixes an unexpected failure with this line, then dumps a Python traceback.
+_UNEXPECTED = "The command failed with an unexpected error. Here is the traceback:"
+INSTALL_HINT = "install it: https://learn.microsoft.com/cli/azure/install-azure-cli"
+
+
+class AzCliError(CommandError):
+    """The Azure CLI is missing, or a command it ran failed."""
+
+
+class AzureCliRunner(CommandRunner):
+    """Runs ``az`` commands with JSON output and checks their exit codes."""
+
+    error_type = AzCliError
+
+    def __init__(self, executable: str | None = None, *, runner: Runner | None = None) -> None:
+        options = {"runner": runner} if runner is not None else {}
+        super().__init__("az", executable, install_hint=INSTALL_HINT, **options)
+
+    def run_json(self, *args: str) -> Any:
+        """Run ``az`` with JSON output and return the parsed value (None for no output)."""
+        return super().run_json(*args, "--output", "json", "--only-show-errors")
+
+    def clean_stderr(self, stderr: str | None) -> str:
+        return clean_stderr(stderr)
+
+    def hint_for(self, detail: str) -> str | None:
+        return hint_for(detail)
+
+
+def clean_stderr(stderr: str | None) -> str:
+    """The error message from ``az`` stderr, without any Python traceback after it."""
+    lines: list[str] = []
+    for raw in (stderr or "").splitlines():
+        line = raw.strip()
+        if line.startswith("Traceback (most recent call last)"):
+            break
+        line = line.removeprefix("ERROR: ")
+        if line and line != _UNEXPECTED:
+            lines.append(line)
+    return " ".join(lines)[:1000]
+
+
+def signed_out(message: str) -> bool:
+    """True when an ``az`` error means there is no usable session."""
+    return "az login" in message
+
+
+def hint_for(detail: str) -> str | None:
+    """A next step for a failed ``az`` command, when the message points to one."""
+    if "Unable to get authority configuration" in detail:
+        return (
+            "no such tenant: check the tenant id (for a profile, its tenant_id in the config file)"
+        )
+    if signed_out(detail) or "AADSTS" in detail:
+        return "the Azure CLI session is missing or expired; sign in again (az login --tenant <id>)"
+    return None