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

libre_devops_helpers/microsoft/logicapps/client.py

@@ -0,0 +1,162 @@
+"""Consumption Logic Apps in Azure: read deployed workflows, and ask Azure to validate one.
+
+Validating goes to the resource provider's validate endpoint, which type-checks a whole
+definition and gives the provider's own verdict while creating and costing nothing. It
+is the authority the offline checks defer to: whether a property is accepted on the API
+version, whether an expression type-checks, whether a connector action is well formed.
+It validates the definition, not the estate around it, so a missing dispatch target
+(``NestedWorkflowNotFound``) is for ``deploy_order`` to prevent, not for this to catch.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Self
+from urllib.parse import quote
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import ApiError, InputError, NotFoundError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.core.util import is_guid
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+from libre_devops_helpers.microsoft.logicapps.document import WorkflowDocument
+
+API_VERSION = "2019-05-01"
+_GROUP_API = "2021-04-01"
+_NAME = re.compile(r"^[A-Za-z0-9._()-]{1,90}$")
+_LOCATION = re.compile(r"^[a-z0-9]{2,40}$")
+
+
+@dataclass(frozen=True)
+class Validation:
+    """The provider's verdict on a definition."""
+
+    workflow: str
+    location: str
+    valid: bool
+    code: str | None
+    message: str
+
+
+class LogicAppsClient:
+    """Reads Consumption Logic App workflows through ARM. Close it when done."""
+
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+
+    @classmethod
+    def create(
+        cls,
+        tokens: TokenProvider,
+        tenant_id: str,
+        *,
+        arm_url: str = PUBLIC.arm_url,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> Self:
+        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,
+    ) -> Self:
+        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 workflows(self, subscription: str, resource_group: str) -> list[dict[str, Any]]:
+        """Every Consumption workflow in the resource group, as ARM returns it."""
+        path = f"{_group_path(subscription, resource_group)}/providers/Microsoft.Logic/workflows"
+        return list(
+            self.api.get_all(path, params={"api-version": API_VERSION}, next_link="nextLink")
+        )
+
+    def workflow(self, subscription: str, resource_group: str, name: str) -> dict[str, Any]:
+        """One workflow, whole: its definition, parameter values and all."""
+        group = _group_path(subscription, resource_group)
+        path = f"{group}/providers/Microsoft.Logic/workflows/{_name(name)}"
+        try:
+            return self.api.get(path, params={"api-version": API_VERSION})
+        except ApiError as exc:
+            if exc.status == 404:
+                raise NotFoundError(f"no workflow {name!r} in {resource_group}") from None
+            raise
+
+    def location_of(self, subscription: str, resource_group: str) -> str:
+        """The resource group's region, where a workflow in it would live."""
+        group = self.api.get(
+            _group_path(subscription, resource_group), params={"api-version": _GROUP_API}
+        )
+        location = group.get("location")
+        if not isinstance(location, str) or not location:
+            raise ApiError(f"resource group {resource_group} has no location")
+        return location
+
+    def validate(
+        self,
+        document: WorkflowDocument,
+        *,
+        subscription: str,
+        resource_group: str,
+        location: str,
+        name: str | None = None,
+    ) -> Validation:
+        """Ask the provider whether it would accept ``document``; nothing is deployed."""
+        workflow = _name(name or document.name or "ldo-validate-probe")
+        if not _LOCATION.match(location):
+            raise InputError(f"{location!r} is not an Azure region name, such as uksouth")
+        # The body is a workflow resource: the definition, and the parameter VALUES beside
+        # it. A declaration with no value is exactly what the provider rejects.
+        properties: dict[str, Any] = {"definition": dict(document.definition)}
+        if document.parameter_values is not None:
+            properties["parameters"] = dict(document.parameter_values)
+        path = (
+            f"{_group_path(subscription, resource_group)}/providers/Microsoft.Logic"
+            f"/locations/{location}/workflows/{workflow}/validate"
+        )
+        try:
+            self.api.request(
+                "POST",
+                path,
+                params={"api-version": API_VERSION},
+                json_body={"location": location, "properties": properties},
+                allow_empty=True,
+            )
+        except ApiError as exc:
+            if exc.status == 400:
+                return Validation(workflow, location, False, exc.code, str(exc))
+            raise
+        return Validation(workflow, location, True, None, "accepted")
+
+
+def _group_path(subscription: str, resource_group: str) -> str:
+    if not is_guid(subscription):
+        raise InputError(f"{subscription!r} is not a subscription id")
+    if not re.match(r"^[-\w._()]{1,90}$", resource_group) or resource_group.endswith("."):
+        raise InputError(f"{resource_group!r} is not a resource group name")
+    return f"/subscriptions/{subscription}/resourceGroups/{quote(resource_group)}"
+
+
+def _name(name: str) -> str:
+    if not _NAME.match(name):
+        raise InputError(f"{name!r} is not a Logic App workflow name")
+    return name

libre_devops_helpers/microsoft/logicapps/document.py

@@ -0,0 +1,202 @@
+"""Reading a Consumption Logic App workflow document, whatever shape it arrives in.
+
+A definition arrives in one of three shapes, and the difference matters:
+
+- ``code-view``: the designer's code view, ``{"definition": {...}, "parameters": {...}}``.
+- ``arm``: an ARM resource GET, ``{"properties": {"definition": {...}, ...}, ...}``.
+- ``bare``: a template's bare definition, ``{"$schema": ..., "triggers": ..., "actions": ...}``.
+
+A wrapper's ``parameters`` block holds VALUES; a bare definition's top-level
+``parameters`` holds its DECLARATIONS. Reading one as the other is the classic round-trip
+trap, so the two are always kept apart here. A workflow definition has no top-level
+``definition`` or ``properties`` key of its own, so telling the shapes apart is exact.
+
+Templates for Terraform's ``templatefile`` (``.json.tftpl``) are not JSON while they hold
+``${...}`` tokens; those are blanked first, so their shape can still be checked.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from libre_devops_helpers.core.errors import InputError
+
+TOKEN_MARK = "TFTPL_TOKEN"  # what an unrendered ${...} becomes, so the text parses
+SHAPES = ("code-view", "arm", "bare")
+
+
+@dataclass(frozen=True)
+class WorkflowDocument:
+    """A workflow document, unwrapped: its definition, and the values beside it."""
+
+    source: str
+    name: str | None
+    shape: str
+    definition: Mapping[str, Any]
+    parameter_values: Mapping[str, Any] | None  # None for a bare definition, which has none
+    text: str
+
+    @property
+    def declarations(self) -> Mapping[str, Any] | None:
+        """The parameters the definition declares, or None when it declares none."""
+        value = self.definition.get("parameters")
+        return value if isinstance(value, Mapping) else None
+
+    @property
+    def triggers(self) -> Mapping[str, Any]:
+        value = self.definition.get("triggers")
+        return value if isinstance(value, Mapping) else {}
+
+    @property
+    def actions(self) -> Mapping[str, Any]:
+        value = self.definition.get("actions")
+        return value if isinstance(value, Mapping) else {}
+
+
+@dataclass(frozen=True)
+class ActionNode:
+    """One action, wherever it sits: ``path`` names it through its containers."""
+
+    name: str
+    path: str
+    action: Mapping[str, Any]
+
+
+def token_safe_json(text: str) -> str:
+    """``text`` with each Terraform ``${...}`` token blanked, so it parses as JSON.
+
+    Where a token sits decides the replacement, which is why this scans rather than using
+    a regex: inside a JSON string it becomes bare text, but standing alone in value
+    position (``"interval": ${x}``) it needs quotes of its own. Escapes and brace nesting
+    are tracked, so a token holding braces is one unit. ``$${`` is templatefile's escaped
+    literal (it renders as ``${``), so it is not a token. Logic App expressions use
+    ``@{...}``, so a ``${...}`` is always a Terraform token here.
+    """
+    out: list[str] = []
+    in_string = False
+    index = 0
+    length = len(text)
+    while index < length:
+        char = text[index]
+        if in_string:
+            if char == "\\" and index + 1 < length:
+                out.append(text[index : index + 2])  # an escape carries its next character
+                index += 2
+                continue
+            if char == '"':
+                in_string = False
+                out.append(char)
+                index += 1
+                continue
+        elif char == '"':
+            in_string = True
+            out.append(char)
+            index += 1
+            continue
+        if text.startswith("$${", index):
+            out.append("${")
+            index += 3
+            continue
+        if text.startswith("${", index):
+            end = _token_end(text, index + 1)
+            if end is not None:
+                out.append(TOKEN_MARK if in_string else f'"{TOKEN_MARK}"')
+                index = end + 1
+                continue
+        out.append(char)
+        index += 1
+    return "".join(out)
+
+
+def _token_end(text: str, opening: int) -> int | None:
+    """The index of the brace that closes the one at ``opening``, or None."""
+    depth = 0
+    for position in range(opening, len(text)):
+        if text[position] == "{":
+            depth += 1
+        elif text[position] == "}":
+            depth -= 1
+            if depth == 0:
+                return position
+    return None
+
+
+def load(path: Path) -> WorkflowDocument:
+    """Read and unwrap the document at ``path`` (``.json`` or ``.json.tftpl``)."""
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except FileNotFoundError:
+        raise InputError(f"Logic App definition file not found: {path}") from None
+    except OSError as exc:
+        raise InputError(f"cannot read {path}: {exc}") from None
+    return parse(text, str(path), default_name=workflow_name_from(path))
+
+
+def parse(
+    text: str, source: str = "<string>", *, default_name: str | None = None
+) -> WorkflowDocument:
+    """Unwrap a document already read, from ``source`` (a path, or ``<string>``)."""
+    if not text.strip():
+        raise InputError(f"Logic App definition {source} is empty")
+    try:
+        parsed = json.loads(token_safe_json(text))
+    except ValueError as exc:
+        raise InputError(f"Logic App definition {source} is not JSON: {exc}") from None
+    if not isinstance(parsed, Mapping):
+        raise InputError(f"Logic App definition {source} is not a JSON object")
+    properties = parsed.get("properties")
+    if isinstance(properties, Mapping) and isinstance(properties.get("definition"), Mapping):
+        shape, definition, values = "arm", properties["definition"], properties.get("parameters")
+    elif isinstance(parsed.get("definition"), Mapping):
+        shape, definition, values = "code-view", parsed["definition"], parsed.get("parameters")
+    else:
+        shape, definition, values = "bare", parsed, None
+    name = parsed.get("name") if isinstance(parsed.get("name"), str) else default_name
+    return WorkflowDocument(
+        source=source,
+        name=name,
+        shape=shape,
+        definition=definition,
+        parameter_values=values if isinstance(values, Mapping) else None,
+        text=text,
+    )
+
+
+def workflow_name_from(path: Path) -> str:
+    """``router`` for ``router.json`` or ``router.json.tftpl``."""
+    name = path.name
+    for suffix in (".tftpl", ".json"):
+        name = name.removesuffix(suffix)
+    return name
+
+
+def action_nodes(actions: Mapping[str, Any] | None, prefix: str = "") -> Iterator[ActionNode]:
+    """Every action, however deeply nested, each with its full path.
+
+    The workflow language nests actions: a Scope, Foreach and Until carry ``actions``; an
+    If adds ``else.actions``; a Switch carries ``cases.<name>.actions`` and
+    ``default.actions``. Reading only the top level sees a fraction of the workflow.
+    """
+    if not isinstance(actions, Mapping):
+        return
+    for name, action in actions.items():
+        if not isinstance(action, Mapping):
+            continue
+        path = f"{prefix}/{name}" if prefix else name
+        yield ActionNode(name, path, action)
+        containers: list[Any] = [action.get("actions")]
+        for branch in ("else", "default"):
+            node = action.get(branch)
+            if isinstance(node, Mapping):
+                containers.append(node.get("actions"))
+        cases = action.get("cases")
+        if isinstance(cases, Mapping):
+            containers.extend(
+                case.get("actions") for case in cases.values() if isinstance(case, Mapping)
+            )
+        for container in containers:
+            yield from action_nodes(container, path)

libre_devops_helpers/microsoft/pim/__init__.py

@@ -0,0 +1,39 @@
+"""Privileged Identity Management: eligible and active roles, requests, approvals, settings.
+
+Covers the three PIM areas in one shape: Azure resource roles (through Azure Resource
+Manager), Entra roles and PIM for Groups (through Microsoft Graph). Depends only on
+``core`` and the shared Microsoft layer. Every call reads; nothing is activated here.
+
+Public API::
+
+    from libre_devops_helpers.microsoft.pim import AzurePimClient, GraphPimClient
+
+    with AzurePimClient.for_profile(profile, tokens) as azure:
+        eligible = azure.eligible()                    # the signed-in user's
+    with GraphPimClient.for_profile(profile, tokens) as graph:
+        pending = graph.role_requests(approver=True)   # waiting on the signed-in user
+"""
+
+from libre_devops_helpers.microsoft.pim.azure import AzurePimClient
+from libre_devops_helpers.microsoft.pim.entra import GraphPimClient
+from libre_devops_helpers.microsoft.pim.models import (
+    AREAS,
+    Area,
+    PimAssignment,
+    PimRequest,
+    PimSettings,
+)
+from libre_devops_helpers.microsoft.pim.permissions import REQUIREMENTS
+from libre_devops_helpers.microsoft.pim.rules import settings_from_rules
+
+__all__ = [
+    "AREAS",
+    "REQUIREMENTS",
+    "Area",
+    "AzurePimClient",
+    "GraphPimClient",
+    "PimAssignment",
+    "PimRequest",
+    "PimSettings",
+    "settings_from_rules",
+]

libre_devops_helpers/microsoft/pim/azure.py

@@ -0,0 +1,238 @@
+"""PIM for Azure resources, through Azure Resource Manager.
+
+Access rests on Azure RBAC, so the Azure CLI's token works; the tenant needs Microsoft
+Entra ID P2 or ID Governance. "Mine" views are asked at the root scope with ARM's own
+filters (``asTarget()``, ``asRequestor()``, ``asApprover()``); a named principal is asked
+per subscription with ``assignedTo()``, which includes roles held through a group and
+those inherited from above.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, Self
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider, token_source
+from libre_devops_helpers.core.errors import 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 PimAssignment, PimRequest, PimSettings
+from libre_devops_helpers.microsoft.pim.rules import settings_from_rules
+
+PIM_API = "2020-10-01"
+ROLES_API = "2022-04-01"
+_AUTHZ = "providers/Microsoft.Authorization"
+
+
+class AzurePimClient:
+    """PIM for Azure resources. 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,
+        *,
+        arm_url: str = PUBLIC.arm_url,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> AzurePimClient:
+        api = ApiClient(
+            arm_url,
+            token_source(tokens, arm_url.rstrip("/") + "/", tenant_id),
+            name="Azure 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,
+    ) -> AzurePimClient:
+        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()
+
+    def eligible(
+        self, *, principal_id: str | None = None, scopes: Iterable[str] = ()
+    ) -> list[PimAssignment]:
+        """Eligible role assignments: the signed-in user's, or ``principal_id``'s."""
+        return self._instances("roleEligibilityScheduleInstances", "eligible", principal_id, scopes)
+
+    def active(
+        self, *, principal_id: str | None = None, scopes: Iterable[str] = ()
+    ) -> list[PimAssignment]:
+        """Active role assignments, activated through PIM or standing."""
+        return self._instances("roleAssignmentScheduleInstances", "active", principal_id, scopes)
+
+    def requests(
+        self, *, approver: bool = False, principal_id: str | None = None, scopes: Iterable[str] = ()
+    ) -> list[PimRequest]:
+        """Requests the signed-in user made, or ones waiting on them with ``approver``."""
+        if principal_id:
+            pairs = [
+                (scope, f"principalId eq {odata_string(_guid(principal_id))}")
+                for scope in _scopes(scopes)
+            ]
+        else:
+            pairs = [("", "asApprover()" if approver else "asRequestor()")]
+        found: dict[str, PimRequest] = {}
+        for scope, expression in pairs:
+            for item in self._list(scope, "roleAssignmentScheduleRequests", expression):
+                request = _request(item)
+                found.setdefault(request.id, request)
+        return sorted(found.values(), key=lambda item: str(item.created or ""), reverse=True)
+
+    def settings(self, role: str, scope: str) -> PimSettings:
+        """A role's PIM settings at ``scope`` (a subscription, resource group or resource)."""
+        scope = _scope(scope)
+        definitions = list(
+            self.api.get_all(
+                f"{scope}/{_AUTHZ}/roleDefinitions",
+                params={"api-version": ROLES_API, "$filter": f"roleName eq {odata_string(role)}"},
+                next_link="nextLink",
+            )
+        )
+        if not definitions:
+            raise NotFoundError(f"no Azure role is named {role!r} at {scope}")
+        definition_id = str(definitions[0].get("id") or "")
+        items = list(
+            self.api.get_all(
+                f"{scope}/{_AUTHZ}/roleManagementPolicyAssignments",
+                params={
+                    "api-version": PIM_API,
+                    "$filter": f"roleDefinitionId eq {odata_string(definition_id)}",
+                },
+                next_link="nextLink",
+            )
+        )
+        if not items:
+            raise NotFoundError(f"no PIM settings for {role!r} at {scope}")
+        properties = items[0].get("properties")
+        properties = properties if isinstance(properties, Mapping) else {}
+        rules = properties.get("effectiveRules") or []
+        return settings_from_rules("azure", role, scope, rules if isinstance(rules, list) else [])
+
+    def _instances(
+        self, collection: str, state: str, principal_id: str | None, scopes: Iterable[str]
+    ) -> list[PimAssignment]:
+        if principal_id:
+            expression = f"assignedTo({odata_string(_guid(principal_id))})"
+            pairs = [(scope, expression) for scope in _scopes(scopes)]
+        else:
+            pairs = [("", "asTarget()")]
+        found: dict[str, PimAssignment] = {}
+        for scope, expression in pairs:
+            for item in self._list(scope, collection, expression):
+                assignment = _assignment(item, state)
+                found.setdefault(str(item.get("id") or id(item)), assignment)
+        return sorted(found.values(), key=lambda item: (item.role.casefold(), item.scope))
+
+    def _list(self, scope: str, collection: str, expression: str) -> list[dict[str, Any]]:
+        return list(
+            self.api.get_all(
+                f"{scope}/{_AUTHZ}/{collection}",
+                params={"api-version": PIM_API, "$filter": expression},
+                next_link="nextLink",
+            )
+        )
+
+
+def _assignment(item: Mapping[str, Any], state: str) -> PimAssignment:
+    properties = _map(item.get("properties"))
+    expanded = _map(properties.get("expandedProperties"))
+    principal = _map(expanded.get("principal"))
+    role = _map(expanded.get("roleDefinition"))
+    scope = _map(expanded.get("scope"))
+    return PimAssignment(
+        area="azure",
+        state="eligible" if state == "eligible" else "active",
+        role=str(role.get("displayName") or properties.get("roleDefinitionId") or ""),
+        scope=str(scope.get("displayName") or properties.get("scope") or ""),
+        principal_id=str(properties.get("principalId") or ""),
+        principal_name=str(principal.get("displayName") or principal.get("email") or ""),
+        member_type=str(properties.get("memberType") or ""),
+        assignment_type=str(properties.get("assignmentType") or ""),
+        starts=parse_datetime(properties.get("startDateTime")),
+        ends=parse_datetime(properties.get("endDateTime")),
+        raw=dict(item),
+    )
+
+
+def _request(item: Mapping[str, Any]) -> PimRequest:
+    properties = _map(item.get("properties"))
+    expanded = _map(properties.get("expandedProperties"))
+    schedule = _map(properties.get("scheduleInfo"))
+    expiration = _map(schedule.get("expiration"))
+    ticket = _map(properties.get("ticketInfo"))
+    return PimRequest(
+        area="azure",
+        id=str(item.get("id") or ""),
+        action=str(properties.get("requestType") or ""),
+        status=str(properties.get("status") or ""),
+        role=str(_map(expanded.get("roleDefinition")).get("displayName") or ""),
+        scope=str(_map(expanded.get("scope")).get("displayName") or properties.get("scope") or ""),
+        principal_id=str(properties.get("principalId") or ""),
+        principal_name=str(_map(expanded.get("principal")).get("displayName") or ""),
+        justification=str(properties.get("justification") or ""),
+        created=parse_datetime(properties.get("createdOn")),
+        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 _map(value: object) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _guid(value: str) -> str:
+    if not is_guid(value):
+        raise LdoError(f"not an object id: {value!r}")
+    return value.strip().lower()
+
+
+def _scope(value: str) -> str:
+    """An ARM scope, checked: '/subscriptions/<id>...' or a management group."""
+    scope = "/" + value.strip().strip("/")
+    if not (
+        scope.startswith("/subscriptions/") or scope.startswith("/providers/Microsoft.Management/")
+    ):
+        raise LdoError(
+            f"not an Azure scope: {value!r}",
+            hint="use /subscriptions/<id>[/resourceGroups/<name>...] or a management group",
+        )
+    if ".." in scope or "://" in scope:
+        raise LdoError(f"not an Azure scope: {value!r}")
+    return scope
+
+
+def _scopes(values: Iterable[str]) -> list[str]:
+    scopes = [_scope(value) for value in values]
+    if not scopes:
+        raise LdoError("a named principal needs at least one scope to search")
+    return scopes