patcherctl 1.3.5b1__py3-none-any.whl

patcher/__about__.py

@@ -0,0 +1,2 @@
+__title__ = "patcher"
+__version__ = "1.3.5b1"

patcher/cli.py

@@ -0,0 +1,154 @@
+import asyncio
+from typing import AnyStr, Optional
+
+import asyncclick as click
+
+from .__about__ import __version__
+from .client.api_client import ApiClient
+from .client.config_manager import ConfigManager
+from .client.report_manager import ReportManager
+from .client.setup import Setup
+from .client.token_manager import TokenManager
+from .client.ui_manager import UIConfigManager
+from .models.reports.excel_report import ExcelReport
+from .models.reports.pdf_report import PDFReport
+from .utils.animation import Animation
+from .utils.exceptions import PatcherError
+from .utils.logger import LogMe
+
+DATE_FORMATS = {
+    "Month-Year": "%B %Y",  # April 2024
+    "Month-Day-Year": "%B %d %Y",  # April 21 2024
+    "Year-Month-Day": "%Y %B %d",  # 2024 April 21
+    "Day-Month-Year": "%d %B %Y",  # 16 April 2024
+    "Full": "%A %B %d %Y",  # Thursday September 26 2013
+}
+
+
+@click.command()
+@click.version_option(version=__version__)
+@click.option(
+    "--path",
+    "-p",
+    type=click.Path(),
+    required=False,  # Defaulting to false in favor of `--reset`
+    help="Path to save the report(s)",
+)
+@click.option(
+    "--pdf",
+    "-f",
+    is_flag=True,
+    help="Generate a PDF report along with Excel spreadsheet",
+)
+@click.option(
+    "--sort",
+    "-s",
+    type=click.STRING,
+    required=False,
+    help="Sort patch reports by a specified column.",
+)
+@click.option(
+    "--omit",
+    "-o",
+    is_flag=True,
+    help="Omit software titles with patches released in last 48 hours",
+)
+@click.option(
+    "--date-format",
+    "-d",
+    type=click.Choice(list(DATE_FORMATS.keys()), case_sensitive=False),
+    default="Month-Day-Year",
+    help="Specify the date format for the PDF header from predefined choices.",
+)
+@click.option(
+    "--ios",
+    "-m",
+    is_flag=True,
+    help="Include the amount of enrolled mobile devices on the latest version of their respective OS.",
+)
+@click.option(
+    "--concurrency",
+    type=click.INT,
+    default=5,
+    help="Set the maximum concurrency level for API calls.",
+)
+@click.option(
+    "--debug",
+    "-x",
+    is_flag=True,
+    default=False,
+    help="Enable debug logging to see detailed debug messages.",
+)
+@click.option(
+    "--reset",
+    "-r",
+    is_flag=True,
+    default=False,
+    help="Resets the setup process and triggers the setup assistant again.",
+)
+@click.option(
+    "--custom-ca-file",
+    type=click.Path(),
+    required=False,
+    help="Path to a custom CA file for SSL verification.",
+)
+@click.pass_context
+async def main(
+    ctx: click.Context,
+    path: AnyStr,
+    pdf: bool,
+    sort: Optional[AnyStr],
+    omit: bool,
+    date_format: AnyStr,
+    ios: bool,
+    concurrency: int,
+    debug: bool,
+    reset: bool,
+    custom_ca_file: Optional[str],
+) -> None:
+    if not ctx.params["reset"] and not ctx.params["path"]:
+        raise click.UsageError("The --path option is required unless --reset is specified.")
+
+    config = ConfigManager()
+    ui_config = UIConfigManager(custom_ca_file=custom_ca_file)
+    setup = Setup(config=config, ui_config=ui_config, custom_ca_file=custom_ca_file)
+
+    log = LogMe(__name__, debug=debug)
+    animation = Animation(enable_animation=not debug)
+
+    async with animation.error_handling(log):
+        if not setup.completed:
+            await setup.prompt_method(animator=animation)
+            click.echo(click.style(text="Setup has completed successfully!", fg="green", bold=True))
+            click.echo("Patcher is now ready for use.")
+            click.echo("You can use the --help flag to view available options.")
+            click.echo("For more information, visit the project docs: https://patcher.liquidzoo.io")
+            return
+        elif reset:
+            await animation.update_msg("Resetting elements...")
+            await setup.reset()
+            click.echo(click.style(text="Reset has completed as expected!", fg="green", bold=True))
+            return
+
+        jamf_client = config.attach_client(custom_ca_file=custom_ca_file)
+        if jamf_client is None:
+            raise PatcherError(message="Invalid JamfClient configuration detected!")
+
+        token_manager = TokenManager(config)
+
+        api_client = ApiClient(config)
+        api_client.jamf_client = jamf_client
+        excel_report = ExcelReport()
+        pdf_report = PDFReport(ui_config)
+        api_client.jamf_client.set_max_concurrency(concurrency=concurrency)
+
+        patcher = ReportManager(
+            config, token_manager, api_client, excel_report, pdf_report, ui_config, debug
+        )
+
+        actual_format = DATE_FORMATS[date_format]
+        await patcher.process_reports(path, pdf, sort, omit, ios, actual_format)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

patcher/client/__init__.py

@@ -0,0 +1 @@
+

patcher/client/api_client.py

@@ -0,0 +1,301 @@
+import asyncio
+import json
+import ssl
+import subprocess
+from datetime import datetime
+from typing import AnyStr, Dict, List, Optional
+
+import aiohttp
+
+from patcher.utils.wrappers import check_token
+
+from ..models.patch import PatchTitle
+from ..utils import logger
+from .config_manager import ConfigManager
+from .token_manager import TokenManager
+
+
+class ApiClient:
+    """
+    Provides methods for interacting with the Jamf API, specifically fetching patch data, device information, and OS versions.
+
+    The ``ApiClient`` manages authentication and session handling, ensuring efficient and secure communication with the Jamf API.
+    """
+
+    def __init__(self, config: ConfigManager):
+        """
+        Initializes the ApiClient with the provided :class:`~patcher.client.config_manager.ConfigManager`.
+
+        This sets up the API client with necessary credentials and session parameters for interacting with the Jamf API.
+
+        .. seealso::
+            :mod:`~patcher.models.jamf_client`
+
+        :param config: Instance of ConfigManager for loading and storing credentials.
+        :type config: ConfigManager
+        :raises ValueError: If the JamfClient configuration is invalid.
+        """
+        self.log = logger.LogMe(self.__class__.__name__)
+        self.log.debug("Initializing ApiClient")
+        self.config = config
+        self.jamf_client = config.attach_client()
+        if self.jamf_client:
+            self.token = self.jamf_client.token
+            self.log.info("JamfClient and token successfully attached")
+        else:
+            self.log.error("Invalid JamfClient configuration detected!")
+            raise ValueError("Invalid JamfClient configuration detected!")
+        self.jamf_url = self.jamf_client.base_url
+        self.headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.token}",
+        }
+        self.token_manager = TokenManager(config)
+        self.max_concurrency = self.jamf_client.max_concurrency
+        self.ssl_context = ssl.create_default_context(cafile=self.jamf_client.cafile)
+
+    def convert_timezone(self, utc_time_str: AnyStr) -> Optional[AnyStr]:
+        """
+        Converts a UTC time string to a formatted string without timezone information.
+
+        :param utc_time_str: UTC time string in ISO 8601 format (e.g., "2023-08-09T12:34:56+0000").
+        :type utc_time_str: AnyStr
+        :return: Formatted date string (e.g., "Aug 09 2023") or None if the input format is invalid.
+        :rtype: Optional[AnyStr]
+        :example:
+
+        .. code-block:: python
+
+            formatted_date = api_client.convert_timezone("2023-08-09T12:34:56+0000")
+            print(formatted_date)   # Outputs: "Aug 09 2023"
+
+        .. note::
+
+            This function is primarily used 'privately' by methods and classes and is not designed to be called explicitly.
+
+        """
+        try:
+            utc_time = datetime.strptime(utc_time_str, "%Y-%m-%dT%H:%M:%S%z")
+            time_str = utc_time.strftime("%b %d %Y")
+            return time_str
+        except ValueError as e:
+            self.log.error(f"Invalid time format provided. Details: {e}")
+            return None
+
+    async def fetch_json(self, url: AnyStr, session: aiohttp.ClientSession) -> Optional[Dict]:
+        """
+        Asynchronously fetches JSON data from a specified URL using a session.
+
+        :param url: URL to fetch the JSON data from.
+        :type url: AnyStr
+        :param session: An aiohttp.ClientSession instance used to make the request.
+        :type session: aiohttp.ClientSession
+        :return: JSON data as a dictionary or None if an error occurs.
+        :rtype: Optional[Dict]
+        :example:
+
+        .. code-block:: python
+
+            async with aiohttp.ClientSession() as session:
+                json_data = await api_client.fetch_json("https://api.example.com/data", session)
+                if json_data:
+                    print(json_data)
+        """
+        self.log.debug(f"Fetching JSON data from URL: {url}")
+        try:
+            async with session.get(url, headers=self.headers, ssl=self.ssl_context) as response:
+                response.raise_for_status()
+                json_data = await response.json()
+                self.log.info(f"Successfully fetched JSON data from {url}")
+                return json_data
+        except aiohttp.ClientResponseError as e:
+            self.log.error(f"Received a client error while fetching JSON from {url}: {e}")
+        except Exception as e:
+            self.log.error(f"Error fetching JSON: {e}")
+        return None
+
+    async def fetch_batch(self, urls: List[AnyStr]) -> List[Optional[Dict]]:
+        """
+        Fetches JSON data in batches to respect the concurrency limit. Data is fetched
+        from each URL in the provided list, ensuring that no more than ``max_concurrency``
+        requests are sent concurrently.
+
+        :param urls: List of URLs to fetch data from.
+        :type urls: List[AnyStr]
+        :return: A list of JSON dictionaries or None for URLs that fail to retrieve data.
+        :rtype: List[Optional[Dict]]
+        """
+        results = []
+        async with aiohttp.ClientSession() as session:
+            for i in range(0, len(urls), self.max_concurrency):
+                batch = urls[i : i + self.max_concurrency]
+                tasks = [self.fetch_json(url, session) for url in batch]
+                batch_results = await asyncio.gather(*tasks)
+                results.extend(batch_results)
+        return results
+
+    @check_token
+    async def get_policies(self) -> Optional[List]:
+        """
+        Retrieves a list of patch software title IDs from the Jamf API. This function
+        requires a valid authentication token, which is managed automatically.
+
+        :return: A list of software title IDs or None if an error occurs.
+        :rtype: Optional[List]
+        """
+        async with aiohttp.ClientSession() as session:
+            url = f"{self.jamf_url}/api/v2/patch-software-title-configurations"
+            response = await self.fetch_json(url=url, session=session)
+
+            # Verify response is list type as expected
+            if not isinstance(response, list):
+                self.log.error(
+                    f"Unexpected response format: expected a list, received {type(response)} instead."
+                )
+                return None
+
+            # Check if all elements in the list are dictionaries
+            if not all(isinstance(item, dict) for item in response):
+                self.log.error("Unexpected response format: all items should be dictionaries.")
+                return None
+
+            self.log.info("Patch policies obtained as expected.")
+            return [title.get("id") for title in response]
+
+    @check_token
+    async def get_summaries(self, policy_ids: List) -> Optional[List[PatchTitle]]:
+        """
+        Retrieves patch summaries for the specified policy IDs from the Jamf API. This function
+        fetches data asynchronously and compiles the results into a list of ``PatchTitle`` objects.
+
+        :param policy_ids: List of policy IDs to retrieve summaries for.
+        :type policy_ids: List
+        :return: List of ``PatchTitle`` objects containing patch summaries or None if an error occurs.
+        :rtype: Optional[List[PatchTitle]]
+        """
+        urls = [
+            f"{self.jamf_url}/api/v2/patch-software-title-configurations/{policy}/patch-summary"
+            for policy in policy_ids
+        ]
+        summaries = await self.fetch_batch(urls)
+
+        policy_summaries = [
+            PatchTitle(
+                title=summary.get("title"),
+                released=self.convert_timezone(summary.get("releaseDate")),
+                hosts_patched=summary.get("upToDate"),
+                missing_patch=summary.get("outOfDate"),
+            )
+            for summary in summaries
+            if summary
+        ]
+        self.log.info(
+            f"Successfully obtained policy summaries for {len(policy_summaries)} policies."
+        )
+        return policy_summaries
+
+    @check_token
+    async def get_device_ids(self) -> Optional[List[int]]:
+        """
+        Asynchronously fetches the list of mobile device IDs from the Jamf Pro API.
+        This method is only called if the :ref:`iOS <ios>` option is passed to the CLI.
+
+        :return: A list of mobile device IDs or None on error.
+        :rtype: Optional[List[int]]
+        """
+        url = f"{self.jamf_url}/api/v2/mobile-devices"
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                response = await self.fetch_json(url=url, session=session)
+        except aiohttp.ClientError as e:
+            self.log.error(f"Error fetching device IDs: {e}")
+            return None
+
+        if not response:
+            self.log.error(f"API call to {url} was unsuccessful.")
+            return None
+
+        devices = response.get("results")
+
+        if not devices:
+            self.log.error("Received empty data set when trying to obtain device IDs.")
+            return None
+
+        self.log.info(f"Received {len(devices)} device IDs successfully.")
+        return [device.get("id") for device in devices if device]
+
+    @check_token
+    async def get_device_os_versions(
+        self,
+        device_ids: List[int],
+    ) -> Optional[List[Dict[AnyStr, AnyStr]]]:
+        """
+        Asynchronously fetches the OS version and serial number for each device ID provided.
+        This method is only called if the :ref:`iOS <ios>` option is passed to the CLI.
+
+        :param device_ids: A list of mobile device IDs to retrieve information for.
+        :type device_ids: List[int]
+        :return: A list of dictionaries containing the serial numbers and OS versions, or None on error.
+        :rtype: Optional[List[Dict[AnyStr, AnyStr]]]
+        """
+        if not device_ids:
+            self.log.error("No device IDs provided!")
+            return None
+        urls = [f"{self.jamf_url}/api/v2/mobile-devices/{device}/detail" for device in device_ids]
+        subsets = await self.fetch_batch(urls)
+
+        if not subsets:
+            self.log.error("Received empty response obtaining device OS information.")
+            return None
+
+        devices = [
+            {
+                "SN": subset.get("serialNumber"),
+                "OS": subset.get("osVersion"),
+            }
+            for subset in subsets
+            if subset
+        ]
+        self.log.info(f"Successfully obtained OS versions for {len(devices)} devices.")
+        return devices
+
+    def get_sofa_feed(self) -> Optional[List[Dict[AnyStr, AnyStr]]]:
+        """
+        Fetches iOS Data feeds from SOFA and extracts latest OS version information.
+        To limit the amount of possible SSL verification checks, this method utilizes a subprocess call
+        instead.
+        This method is only called if the :ref:`iOS <ios>` option is passed to the CLI.
+
+        :return: A list of dictionaries containing base OS versions, latest iOS versions and release dates,
+                or None on error.
+        :rtype: Optional[List[Dict[AnyStr, AnyStr]]]
+        """
+
+        # Utilize curl to avoid SSL Verification errors for end-users on managed devices
+        command = "curl -s 'https://sofafeed.macadmins.io/v1/ios_data_feed.json'"
+
+        try:
+            result = subprocess.run(command, shell=True, capture_output=True, text=True, check=True)
+        except (subprocess.CalledProcessError, aiohttp.ClientResponseError) as e:
+            self.log.error(f"Encountered error executing subprocess command: {e}")
+            return None
+
+        try:
+            data = json.loads(result.stdout)
+        except json.JSONDecodeError as e:
+            self.log.error(f"Error decoding JSON data: {e}")
+            return None
+
+        os_versions = data.get("OSVersions", [])
+        latest_versions = []
+        for version in os_versions:
+            version_info = version.get("Latest", {})
+            latest_versions.append(
+                {
+                    "OSVersion": version.get("OSVersion"),
+                    "ProductVersion": version_info.get("ProductVersion"),
+                    "ReleaseDate": self.convert_timezone(version_info.get("ReleaseDate")),
+                }
+            )
+        return latest_versions

patcher/client/config_manager.py

@@ -0,0 +1,144 @@
+from datetime import datetime, timezone
+from typing import AnyStr, Optional
+
+import keyring
+from pydantic import ValidationError
+
+from ..models.jamf_client import JamfClient
+from ..models.token import AccessToken
+from ..utils import logger
+
+
+class ConfigManager:
+    """
+    Manages configuration settings, primarily focused on handling credentials stored in the macOS keychain.
+
+    This class provides methods to securely store, retrieve, and manage sensitive information such as
+    API tokens and client credentials. It integrates with the ``keyring`` library to interface with the macOS keychain.
+    """
+
+    def __init__(self, service_name: AnyStr = "Patcher"):
+        """
+        Initializes the ConfigManager with a specific service name.
+
+        This service name is used as a namespace for storing and retrieving credentials in the keyring,
+        allowing you to organize credentials by the service they pertain to.
+
+        :param service_name: The name of the service for storing credentials in the keyring.
+            Defaults to 'Patcher'.
+        :type service_name: AnyStr
+        :example:
+
+        .. code-block:: python
+
+            config = ConfigManager("MyService")
+        """
+        self.log = logger.LogMe(self.__class__.__name__)
+        self.service_name = service_name
+        self.log.debug(f"Initializing ConfigManager with service name: {service_name}")
+
+    def get_credential(self, key: AnyStr) -> AnyStr:
+        """
+        Retrieves a specified credential from the keyring associated with the given key.
+
+        This method is useful for accessing stored credentials without hardcoding them in scripts.
+        It ensures that sensitive data like passwords or API tokens are securely stored and retrieved.
+
+        :param key: The key of the credential to retrieve, typically a descriptive name like 'API_KEY'.
+        :type key: AnyStr
+        :return: The retrieved credential value. If the key does not exist, returns ``None``.
+        :rtype: AnyStr
+        :example:
+
+        .. code-block:: python
+
+            token = config.get_credential("API_TOKEN")
+        """
+        self.log.debug(f"Retrieving credential for key: {key}")
+        credential = keyring.get_password(self.service_name, key)
+        if credential:
+            self.log.info(f"Credential for key '{key}' retrieved successfully")
+        else:
+            self.log.warning(f"No credential found for key: {key}")
+        return credential
+
+    def set_credential(self, key: AnyStr, value: AnyStr):
+        """
+        Stores a credential in the keyring under the specified key.
+
+        Method is used to securely store sensitive data such as Jamf URL, API Tokens, usernames
+        and passwords.
+
+        :param key: The key under which the credential will be stored. This acts as an identifier for the credential.
+        :type key: AnyStr
+        :param value: The value of the credential to store, such as a password or API token.
+        :type value: AnyStr
+        """
+        self.log.debug(f"Setting credential for key: {key}")
+        keyring.set_password(self.service_name, key, value)
+        self.log.info(f"Credential for key '{key}' set successfully")
+
+    def load_token(self) -> AccessToken:
+        """
+        Loads the access token and its expiration from the keyring.
+
+        :return: An :class:`~patcher.models.token.AccessToken` object containing the token and its
+            expiration date.
+        :rtype: AccessToken
+        """
+        self.log.debug("Loading token from keyring")
+        token = self.get_credential("TOKEN") or ""
+        expires = (
+            self.get_credential("TOKEN_EXPIRATION")
+            or datetime(1970, 1, 1, tzinfo=timezone.utc).isoformat()
+        )
+        self.log.info("Token and expiration loaded from keyring")
+        return AccessToken(token=token, expires=expires)
+
+    def attach_client(self, custom_ca_file: Optional[str] = None) -> Optional[JamfClient]:
+        """
+        Creates and returns a :mod:`patcher.models.jamf_client` object using the stored credentials.
+        Allows for an optional custom CA file to be passed, which can be useful for environments
+        with custom certificate authorities.
+
+        :param custom_ca_file: Optional path to a custom CA file for SSL verification.
+        :type custom_ca_file: Optional[str]
+        :return: The ``JamfClient`` object if validation is successful, None otherwise.
+        :rtype: Optional[JamfClient]
+        """
+        self.log.debug("Attaching Jamf client with stored credentials")
+        try:
+            client = JamfClient(
+                client_id=self.get_credential("CLIENT_ID"),
+                client_secret=self.get_credential("CLIENT_SECRET"),
+                server=self.get_credential("URL"),
+                token=self.load_token(),
+                custom_ca_file=custom_ca_file,
+            )
+            self.log.info("Jamf client attached successfully")
+            return client
+        except ValidationError as e:
+            self.log.error(f"Jamf Client failed validation: {e}")
+            return None
+
+    def create_client(self, client: JamfClient):
+        """
+        Stores a `JamfClient` object's credentials in the keyring.
+
+        This method is typically used during the setup process to save the credentials and token of a `JamfClient`
+        object into the keyring for secure storage and later use.
+
+        :param client: The `JamfClient` object whose credentials will be stored.
+        :type client: JamfClient
+        """
+        self.log.debug(f"Setting Jamf client: {client.client_id}")
+        credentials = {
+            "CLIENT_ID": client.client_id,
+            "CLIENT_SECRET": client.client_secret,
+            "URL": client.server,
+            "TOKEN": client.token.token,
+            "TOKEN_EXPIRATION": client.token.expires.isoformat(),
+        }
+        for key, value in credentials.items():
+            self.set_credential(key, value)
+        self.log.info("Jamf client credentials and token saved successfully")