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

libre_devops_helpers/microsoft/automation/client.py

@@ -0,0 +1,241 @@
+"""Azure Automation through ARM: accounts, the jobs their runbooks ran, and the jobs' logs.
+
+A job is one run of a runbook. It writes streams, as the portal's job page shows them:
+output, warnings, errors, and verbose, progress and debug records when the runbook turns
+those on. Jobs are kept for 30 days. Everything here reads: nothing starts, stops or
+changes a runbook.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from typing import 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 AmbiguousError, 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.automation.models import AutomationAccount, Job, JobStream
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+from libre_devops_helpers.microsoft.config import Profile
+
+API_VERSION = "2023-11-01"
+PROVIDER = "Microsoft.Automation/automationAccounts"
+# What each part of a path may hold, so nothing typed can reach another resource.
+_ACCOUNT = re.compile(r"^[A-Za-z0-9-]{1,50}$")
+_GROUP = re.compile(r"^[A-Za-z0-9._()-]{1,90}$")
+_JOB = re.compile(r"^[A-Za-z0-9-]{1,64}$")
+_STREAM = re.compile(r"^[A-Za-z0-9:._-]{1,128}$")
+_ACCOUNT_ID = re.compile(
+    r"^/subscriptions/(?P<subscription>[^/]+)/resourceGroups/(?P<group>[^/]+)"
+    r"/providers/Microsoft\.Automation/automationAccounts/(?P<name>[^/]+)$",
+    re.IGNORECASE,
+)
+
+
+class AutomationClient:
+    """Reads Automation accounts and their jobs 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 __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # Accounts -----------------------------------------------------------------------
+
+    def accounts(self, subscriptions: Iterable[str]) -> list[AutomationAccount]:
+        """Every Automation account in the subscriptions, by name."""
+        found: list[AutomationAccount] = []
+        for subscription in subscriptions:
+            path = f"/subscriptions/{_guid(subscription)}/providers/{PROVIDER}"
+            found.extend(
+                AutomationAccount.from_json(item)
+                for item in self.api.get_all(
+                    path, params={"api-version": API_VERSION}, next_link="nextLink"
+                )
+            )
+        return sorted(found, key=lambda account: (account.name.casefold(), account.id))
+
+    def find_account(
+        self, ref: str, subscriptions: Sequence[str], *, resource_group: str | None = None
+    ) -> AutomationAccount:
+        """One account, by its resource id, or by name within ``subscriptions``.
+
+        A name several accounts share is refused, with their ids to choose from.
+        """
+        ref = ref.strip()
+        by_id = _ACCOUNT_ID.match(ref)
+        if by_id:
+            path = (
+                f"/subscriptions/{_guid(by_id['subscription'])}/resourceGroups/"
+                f"{_group(by_id['group'])}/providers/{PROVIDER}/{_account(by_id['name'])}"
+            )
+            try:
+                return AutomationAccount.from_json(
+                    self.api.get(path, params={"api-version": API_VERSION})
+                )
+            except ApiError as exc:
+                if exc.status == 404:
+                    raise NotFoundError(f"no Automation account {ref}") from None
+                raise
+        name = _account(ref)
+        matches = [
+            account
+            for account in self.accounts(subscriptions)
+            if account.name.casefold() == name.casefold()
+            and (
+                resource_group is None
+                or account.resource_group.casefold() == resource_group.casefold()
+            )
+        ]
+        if not matches:
+            where = f" in resource group {resource_group}" if resource_group else ""
+            raise NotFoundError(
+                f"no Automation account is named {name!r}{where}",
+                hint="check the subscription (-s), or list them: 'azure automation accounts'",
+            )
+        if len(matches) > 1:
+            raise AmbiguousError(
+                f"{len(matches)} Automation accounts are named {name!r}",
+                hint="pass -g for its resource group, or its resource id: "
+                + ", ".join(account.id for account in matches),
+            )
+        return matches[0]
+
+    # Jobs ---------------------------------------------------------------------------
+
+    def jobs(self, account: AutomationAccount) -> list[Job]:
+        """Every job the account keeps (30 days of them), newest first."""
+        found = [
+            Job.from_json(item)
+            for item in self.api.get_all(
+                f"{_account_path(account)}/jobs",
+                params={"api-version": API_VERSION},
+                next_link="nextLink",
+            )
+        ]
+        return sorted(found, key=_newest_first)
+
+    def job(self, account: AutomationAccount, job_id: str) -> Job:
+        """One job, with what only a single job's GET gives: who started it, and why it failed."""
+        try:
+            data = self.api.get(
+                f"{_account_path(account)}/jobs/{_job(job_id)}", params={"api-version": API_VERSION}
+            )
+        except ApiError as exc:
+            if exc.status == 404:
+                raise NotFoundError(f"no job {job_id} in {account.name}") from None
+            raise
+        return Job.from_json(data)
+
+    def streams(self, account: AutomationAccount, job_id: str) -> list[JobStream]:
+        """Every record the job wrote, oldest first, each with its summary."""
+        found = [
+            JobStream.from_json(item)
+            for item in self.api.get_all(
+                f"{_account_path(account)}/jobs/{_job(job_id)}/streams",
+                params={"api-version": API_VERSION},
+                next_link="nextLink",
+            )
+        ]
+        return sorted(found, key=lambda stream: (stream.time is None, stream.time))
+
+    def stream(self, account: AutomationAccount, job_id: str, stream_id: str) -> JobStream:
+        """One record in full: a listing carries only its summary."""
+        if not _STREAM.match(stream_id):
+            raise InputError(f"{stream_id!r} is not a job stream id")
+        data = self.api.get(
+            f"{_account_path(account)}/jobs/{_job(job_id)}/streams/{quote(stream_id, safe='')}",
+            params={"api-version": API_VERSION},
+        )
+        return JobStream.from_json(data)
+
+    def output(self, account: AutomationAccount, job_id: str) -> str:
+        """The job's output stream as text, as the portal's Output tab shows it."""
+        return self.api.get_text(
+            f"{_account_path(account)}/jobs/{_job(job_id)}/output",
+            params={"api-version": API_VERSION},
+            headers={"Accept": "text/plain"},
+        )
+
+
+def _newest_first(job: Job) -> tuple[bool, float]:
+    when = job.created or job.started
+    return (when is None, -when.timestamp() if when else 0.0)
+
+
+def _account_path(account: AutomationAccount) -> str:
+    matched = _ACCOUNT_ID.match(account.id)
+    if not matched:
+        raise InputError(f"{account.id!r} is not an Automation account's resource id")
+    return (
+        f"/subscriptions/{_guid(matched['subscription'])}/resourceGroups/"
+        f"{_group(matched['group'])}/providers/{PROVIDER}/{_account(matched['name'])}"
+    )
+
+
+def _guid(value: str) -> str:
+    if not is_guid(value):
+        raise InputError(f"{value!r} is not a subscription id")
+    return value
+
+
+def _group(value: str) -> str:
+    if not _GROUP.match(value):
+        raise InputError(f"{value!r} is not a resource group name")
+    return value
+
+
+def _account(value: str) -> str:
+    if not _ACCOUNT.match(value):
+        raise InputError(f"{value!r} is not an Automation account name")
+    return value
+
+
+def _job(value: str) -> str:
+    if not _JOB.match(value.strip()):
+        raise InputError(f"{value!r} is not a job id")
+    return value.strip()

libre_devops_helpers/microsoft/automation/models.py

@@ -0,0 +1,131 @@
+"""Azure Automation accounts, the jobs their runbooks ran, and each job's log streams."""
+
+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
+
+# Job states that need someone to look: the runbook did not finish as it should.
+FAILED = frozenset({"Failed", "Suspended", "Stopped", "Blocked"})
+# The streams a job writes, as the portal's tabs name them, and as ARM spells them.
+STREAMS = {
+    "output": "Output",
+    "error": "Error",
+    "warning": "Warning",
+    "verbose": "Verbose",
+    "progress": "Progress",
+    "debug": "Debug",
+}
+
+
+@dataclass(frozen=True)
+class AutomationAccount:
+    """An Automation account, and where it lives."""
+
+    id: str
+    name: str
+    subscription_id: str
+    resource_group: str
+    location: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> AutomationAccount:
+        resource_id = str(data.get("id") or "")
+        parts = resource_id.split("/")
+        lowered = [part.lower() for part in parts]
+
+        def after(segment: str) -> str:
+            return parts[lowered.index(segment) + 1] if segment in lowered[:-1] else ""
+
+        return cls(
+            id=resource_id,
+            name=str(data.get("name") or ""),
+            subscription_id=after("subscriptions"),
+            resource_group=after("resourcegroups"),
+            location=str(data.get("location") or ""),
+            raw=dict(data),
+        )
+
+    @property
+    def path(self) -> str:
+        """The account's ARM path, which every job request starts from."""
+        return self.id
+
+
+@dataclass(frozen=True)
+class Job:
+    """One run of a runbook."""
+
+    id: str
+    runbook: str
+    status: str
+    created: datetime | None
+    started: datetime | None
+    ended: datetime | None
+    run_on: str
+    started_by: str
+    exception: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> Job:
+        properties = data.get("properties")
+        props: Mapping[str, Any] = properties if isinstance(properties, Mapping) else {}
+        runbook = props.get("runbook")
+        return cls(
+            # The job's resource name is its id: the one the portal shows.
+            id=str(data.get("name") or props.get("jobId") or ""),
+            runbook=str(runbook.get("name") or "") if isinstance(runbook, Mapping) else "",
+            status=str(props.get("status") or ""),
+            created=parse_datetime(props.get("creationTime")),
+            started=parse_datetime(props.get("startTime")),
+            ended=parse_datetime(props.get("endTime")),
+            # Empty for Azure's own sandboxes; a Hybrid Runbook Worker group's name otherwise.
+            run_on=str(props.get("runOn") or ""),
+            started_by=str(props.get("startedBy") or ""),
+            exception=str(props.get("exception") or ""),
+            raw=dict(data),
+        )
+
+    @property
+    def failed(self) -> bool:
+        return self.status in FAILED
+
+    @property
+    def finished(self) -> bool:
+        return self.ended is not None
+
+
+@dataclass(frozen=True)
+class JobStream:
+    """One record a job wrote: a line of output, a warning, an error and so on."""
+
+    id: str
+    time: datetime | None
+    stream: str
+    summary: str
+    text: str
+    raw: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> JobStream:
+        properties = data.get("properties")
+        props: Mapping[str, Any] = properties if isinstance(properties, Mapping) else {}
+        return cls(
+            id=str(props.get("jobStreamId") or ""),
+            time=parse_datetime(props.get("time")),
+            stream=str(props.get("streamType") or ""),
+            summary=str(props.get("summary") or ""),
+            # Only a single stream's GET carries the full text; a listing has the summary.
+            text=str(props.get("streamText") or ""),
+            raw=dict(data),
+        )
+
+    @property
+    def message(self) -> str:
+        return self.text or self.summary

libre_devops_helpers/microsoft/azcli/__init__.py

@@ -0,0 +1,27 @@
+"""Azure CLI context: accounts, sign-in and switching the active account between profiles.
+
+Tokens from the Azure CLI come from ``core.auth.AzureCliCredential``, not from here.
+
+Public API::
+
+    from libre_devops_helpers.microsoft.azcli import AzCli, switch_profile
+
+    result = switch_profile(AzCli(), profile)
+"""
+
+from libre_devops_helpers.microsoft.azcli.client import Account, AzCli
+from libre_devops_helpers.microsoft.azcli.context import (
+    SwitchResult,
+    find_account,
+    match_profile,
+    switch_profile,
+)
+
+__all__ = [
+    "Account",
+    "AzCli",
+    "SwitchResult",
+    "find_account",
+    "match_profile",
+    "switch_profile",
+]

libre_devops_helpers/microsoft/azcli/client.py

@@ -0,0 +1,81 @@
+"""Azure CLI accounts and sign-in.
+
+The subprocess handling lives in ``core.process``; tokens come from
+``core.auth.AzureCliCredential``. This module is only about which accounts the CLI
+knows and which one is active.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from libre_devops_helpers.microsoft.process import AzCliError, AzureCliRunner, signed_out
+
+
+@dataclass(frozen=True)
+class Account:
+    """One entry from ``az account list``: a subscription, or a tenant-level sign-in."""
+
+    id: str
+    name: str
+    tenant_id: str
+    state: str
+    is_default: bool
+    user: str
+
+    @property
+    def tenant_level(self) -> bool:
+        """True for the entry ``az login --allow-no-subscriptions`` records for a tenant."""
+        return self.id == self.tenant_id
+
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> Account:
+        user = data.get("user")
+        return cls(
+            id=str(data.get("id", "")).lower(),
+            name=str(data.get("name", "")),
+            tenant_id=str(data.get("tenantId", "")).lower(),
+            state=str(data.get("state", "")),
+            is_default=bool(data.get("isDefault", False)),
+            user=str(user.get("name", "")) if isinstance(user, Mapping) else "",
+        )
+
+
+class AzCli:
+    """The Azure CLI's accounts: list them, read the active one, switch, sign in."""
+
+    def __init__(self, runner: AzureCliRunner | None = None) -> None:
+        self.runner = runner or AzureCliRunner()
+
+    def current_account(self) -> Account | None:
+        """The active account, or None when the CLI is not signed in."""
+        try:
+            data = self.runner.run_json("account", "show")
+        except AzCliError as exc:
+            if signed_out(str(exc)):
+                return None
+            raise
+        return Account.from_json(data) if isinstance(data, dict) else None
+
+    def accounts(self) -> list[Account]:
+        """Every account the CLI knows, including disabled subscriptions."""
+        data = self.runner.run_json("account", "list", "--all")
+        return [Account.from_json(item) for item in data or [] if isinstance(item, dict)]
+
+    def set_account(self, subscription: str) -> None:
+        """Make ``subscription`` (an id or tenant-level entry) the active account."""
+        self.runner.run("account", "set", "--subscription", subscription, "--only-show-errors")
+
+    def login(
+        self, tenant_id: str, *, device_code: bool = False, allow_no_subscriptions: bool = False
+    ) -> None:
+        """Sign in to ``tenant_id`` interactively (browser, or device code)."""
+        args = ["login", "--tenant", tenant_id, "--output", "none"]
+        if device_code:
+            args.append("--use-device-code")
+        if allow_no_subscriptions:
+            args.append("--allow-no-subscriptions")
+        # The account is chosen afterwards by 'az account set'; skip the CLI's own picker.
+        self.runner.run(*args, interactive=True, env={"AZURE_CORE_LOGIN_EXPERIENCE_V2": "off"})

libre_devops_helpers/microsoft/azcli/context.py

@@ -0,0 +1,95 @@
+"""Switch the Azure CLI's active account between configured profiles.
+
+The Azure CLI keeps one active account per user (in ``~/.azure``), so a switch
+applies to every shell at once. The Entra and XDR helpers do not rely on it:
+they request tokens with an explicit ``--tenant``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from libre_devops_helpers.microsoft.azcli.client import Account, AzCli
+from libre_devops_helpers.microsoft.config import Profile
+from libre_devops_helpers.microsoft.process import AzCliError
+
+
+@dataclass(frozen=True)
+class SwitchResult:
+    """What ``switch_profile`` did."""
+
+    profile: Profile
+    account: Account
+    signed_in: bool
+
+
+def find_account(accounts: Iterable[Account], profile: Profile) -> Account | None:
+    """The account that satisfies ``profile``, or None when the CLI has none.
+
+    A subscription profile needs that exact subscription in its tenant. A tenant
+    profile takes any account in the tenant, preferring the one already active
+    (so switching does not needlessly move off a subscription), then the
+    tenant-level entry, then any enabled subscription.
+    """
+    in_tenant = [account for account in accounts if account.tenant_id == profile.tenant_id]
+    if profile.subscription_id:
+        return next((a for a in in_tenant if a.id == profile.subscription_id), None)
+    for preferred in (
+        lambda a: a.is_default,
+        lambda a: a.tenant_level,
+        lambda a: a.state == "Enabled",
+    ):
+        match = next((a for a in in_tenant if preferred(a)), None)
+        if match is not None:
+            return match
+    return in_tenant[0] if in_tenant else None
+
+
+def match_profile(profiles: Iterable[Profile], account: Account) -> Profile | None:
+    """The profile describing ``account``: a subscription match first, then a tenant match."""
+    candidates = list(profiles)
+    for profile in candidates:
+        if profile.subscription_id == account.id and profile.tenant_id == account.tenant_id:
+            return profile
+    for profile in candidates:
+        if profile.subscription_id is None and profile.tenant_id == account.tenant_id:
+            return profile
+    return None
+
+
+def switch_profile(
+    az: AzCli, profile: Profile, *, sign_in: bool = True, device_code: bool = False
+) -> SwitchResult:
+    """Make ``profile`` the Azure CLI's active context, signing in first when needed.
+
+    With ``sign_in=False`` a missing session raises instead of prompting, which
+    suits scripts. The switch is read back and verified before returning.
+    """
+    profile.require_real_ids()
+    account = find_account(az.accounts(), profile)
+    signed_in = False
+    if account is None:
+        if not sign_in:
+            raise AzCliError(
+                f"the Azure CLI has no session for profile {profile.name!r}",
+                hint=f"sign in with: az login --tenant {profile.tenant_id}",
+            )
+        az.login(
+            profile.tenant_id,
+            device_code=device_code,
+            allow_no_subscriptions=profile.subscription_id is None,
+        )
+        signed_in = True
+        account = find_account(az.accounts(), profile)
+        if account is None:
+            raise AzCliError(
+                f"signed in to tenant {profile.tenant_id}, but subscription "
+                f"{profile.subscription_id} is not visible to that account"
+            )
+
+    az.set_account(account.id)
+    current = az.current_account()
+    if current is None or current.id != account.id:
+        raise AzCliError(f"the Azure CLI did not switch to {account.id}")
+    return SwitchResult(profile=profile, account=current, signed_in=signed_in)

libre_devops_helpers/microsoft/azure/__init__.py

@@ -0,0 +1,34 @@
+"""Azure Resource Manager: subscriptions, Resource Graph, RBAC and Defender for Cloud.
+
+Depends only on ``core`` and the shared Microsoft layer. Access rests on Azure RBAC, so
+there are no token scope requirements to declare. Public API::
+
+    from libre_devops_helpers.microsoft.azure import AzureClient
+
+    with AzureClient.for_profile(profile, tokens) as azure:
+        result = azure.resource_graph("resources | summarize count() by type")
+"""
+
+from libre_devops_helpers.microsoft.azure.client import AzureClient
+from libre_devops_helpers.microsoft.azure.models import (
+    Assessment,
+    AzureRoleAssignment,
+    DefenderPlan,
+    SecureScore,
+    SecureScoreControl,
+    Subscription,
+)
+from libre_devops_helpers.microsoft.resources import Requirement
+
+REQUIREMENTS: tuple[Requirement, ...] = ()
+
+__all__ = [
+    "REQUIREMENTS",
+    "Assessment",
+    "AzureClient",
+    "AzureRoleAssignment",
+    "DefenderPlan",
+    "SecureScore",
+    "SecureScoreControl",
+    "Subscription",
+]