kst 1.0.0__py3-none-any.whl

kst/__about__.py

@@ -0,0 +1,2 @@
+APP_NAME = "kst"
+__version__ = "1.0.0"

kst/__init__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

kst/api/__init__.py

@@ -0,0 +1,25 @@
+from .client import ApiClient, ApiConfig
+from .payload import (
+    ApiPayloadType,
+    CustomProfilePayload,
+    CustomScriptPayload,
+    PayloadList,
+    SelfServiceCategoryPayload,
+)
+from .profiles import CustomProfilesResource
+from .scripts import CustomScriptsResource, ExecutionFrequency
+from .self_service import SelfServiceCategoriesResource
+
+__all__ = [
+    "ApiClient",
+    "ApiConfig",
+    "ApiPayloadType",
+    "CustomProfilePayload",
+    "CustomProfilesResource",
+    "CustomScriptPayload",
+    "CustomScriptsResource",
+    "ExecutionFrequency",
+    "PayloadList",
+    "SelfServiceCategoriesResource",
+    "SelfServiceCategoryPayload",
+]

kst/api/client.py

@@ -0,0 +1,195 @@
+import io
+import json
+import logging
+import re
+from urllib.parse import urljoin, urlparse
+
+import requests
+from pydantic import BaseModel, Field, field_validator
+
+from kst.console import OutputConsole
+from kst.exceptions import ApiClientError
+
+console = OutputConsole(logging.getLogger(__name__))
+
+
+class ApiConfig(BaseModel):
+    """A Container for API configuration values.
+
+    Attributes:
+        url (HttpUrl): API URL for the Kandji tenant. Must use the https:// schema.
+        api_token (str): API authentication token for the Kandji tenant.
+
+    """
+
+    url: str = Field(alias="tenant_url")
+    api_token: str = Field(repr=False)
+
+    @field_validator("url", mode="before")
+    @classmethod
+    def validate_url(cls, v) -> str:
+        """Ensure the url is using https and is a valid Kandji API URL."""
+        # Ensure the URL is a string with a https schema
+
+        if isinstance(v, str) and (parsed_url := urlparse(v)).scheme in ("", "http"):
+            if parsed_url.netloc == "":
+                # handle misclassified netloc: https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse
+                v = parsed_url._replace(scheme="https", netloc=parsed_url.path, path="").geturl()
+            else:
+                v = parsed_url._replace(scheme="https").geturl()
+
+        v = v.rstrip("/")  # Normalize without trailing slash
+
+        if not re.fullmatch(r"https://[A-Za-z0-9-]+\.api(\.eu)?\.kandji\.io", v):
+            raise ValueError(
+                "The Tenant URL must be a valid Kandji API URL. "
+                "Please ensure the URL is in the format https://<tenant>.api.kandji.io or https://<tenant>.api.eu.kandji.io."
+            )
+        return v
+
+    @field_validator("api_token", mode="after")
+    @classmethod
+    def validate_token(cls, v: str) -> str:
+        """Ensure the api_token is a uuid4 string."""
+        if not re.fullmatch(r"[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}", v):
+            raise ValueError(
+                "The API token must be a valid UUID4 string. "
+                "Please ensure the token is in the format 12345678-1234-5678-1234-123456789012."
+            )
+        return v
+
+
+class ApiClient:
+    """Basic API client for interacting with the Kandji API.
+
+    The ApiClient class is a thin wrapper around a requests.Session which handles converting
+    resource paths to fully resolved API resources. It also manages passing credential's with
+    requests.
+
+    Attributes:
+        session (requests.Session): The underlying session used by the client.
+
+    Methods:
+        request: Make an generic HTTP request
+        get: Make a GET HTTP request
+        patch: Make a PATCH HTTP request
+        post: Make a POST HTTP request
+        delete: Make a DELETE HTTP request
+        close: Close the internal session object.
+    """
+
+    def __init__(self, config: ApiConfig) -> None:
+        self._config = config
+        self._session = requests.Session()
+        self._update_header()
+
+    @property
+    def session(self) -> requests.Session:
+        """Get the session object for the client.
+
+        Returns:
+            requests.Session: The internal session object
+
+        Raises:
+            ApiClientError: Raised when the session is not open.
+
+        """
+
+        if self._session is None:
+            raise ApiClientError("No open session available.")
+
+        return self._session
+
+    def close(self) -> None:
+        """Close the internal session object."""
+        if self._session is not None:
+            self.session.close()
+            self._session = None
+
+    def _update_header(self):
+        """Update the session headers with the API token."""
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self._config.api_token}",
+                "Accept": "application/json",
+            }
+        )
+
+    def _make_url(self, path: str):
+        """Convert a relative path to a fully qualified URL."""
+        return urljoin(self._config.url, path)
+
+    def request(self, method: str, url: str, *args, **kwargs) -> requests.Response:
+        """Make a generic HTTP request.
+
+        Handles logging and ensures the source query parameter is included.
+
+        Returns:
+            requests.Response: The response object from the request
+
+        Raises:
+            requests.ConnectionError: Raised when the API connection fails
+            requests.HTTPError: Raised when the HTTP request returns an unsuccessful status code
+
+        """
+
+        try:
+            console.debug(f"Making {method} request to {url}")
+
+            # Add the source=kst param to all requests
+            kwargs["params"] = kwargs.get("params", {}) | {"source": "kst"}
+
+            response = self.session.request(method, url, *args, **kwargs)
+
+            console.debug(f"Response status code: {response.status_code}")
+
+            try:
+                headers = "\n" + json.dumps(dict(response.headers), indent=2)
+            except json.JSONDecodeError:
+                headers = response.headers
+            console.debug(f"Response headers: {headers}")
+
+            try:
+                content = "\n" + json.dumps(response.json(), indent=2)
+            except json.JSONDecodeError:
+                content = response.text
+            console.debug(f"Response content: {content}")
+
+            response.raise_for_status()
+        except requests.ConnectionError as error:
+            console.error(f"Connection error occurred: {error}")
+            raise
+        except requests.HTTPError as error:
+            console.error(f"HTTP error occurred: {error.response.status_code}")
+            console.error(f"Response content: {error.response.text}")
+            raise
+
+        return response
+
+    def get(self, path: str) -> requests.Response:
+        """Make a GET HTTP request to the resolved API endpoint at path."""
+        return self.request("GET", self._make_url(path))
+
+    def patch(
+        self,
+        path: str,
+        data: dict | None = None,
+        json: dict | None = None,
+        files: list[tuple[str, tuple[str, io.BufferedReader, str]]] | None = None,
+    ) -> requests.Response:
+        """Make a PATCH HTTP request to the resolved API endpoint at path."""
+        return self.request("PATCH", self._make_url(path), data=data, json=json, files=files)
+
+    def post(
+        self,
+        path: str,
+        data: dict | None = None,
+        json: dict | None = None,
+        files: list[tuple[str, tuple[str, io.BufferedReader, str]]] | None = None,
+    ) -> requests.Response:
+        """Make a POST HTTP request to the resolved API endpoint at path."""
+        return self.request("POST", self._make_url(path), data=data, json=json, files=files)
+
+    def delete(self, path: str) -> requests.Response:
+        """Make a DELETE HTTP request to the resolved API endpoint at path."""
+        return self.request("DELETE", self._make_url(path))

kst/api/payload.py

@@ -0,0 +1,64 @@
+from typing import Annotated, Generic, TypeVar
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, field_validator
+
+ApiPayloadType = TypeVar("ApiPayloadType", "CustomProfilePayload", "CustomScriptPayload")
+
+
+class CustomProfilePayload(BaseModel):
+    """Payload model for custom profiles API endpoints."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("profile", mode="after")
+    @classmethod
+    def tabs_to_spaces(cls, v: str) -> str:
+        return v.expandtabs(tabsize=4)
+
+    id: Annotated[str, AfterValidator(lambda value: value.lower())]
+    name: str
+    active: bool
+    profile: str
+    mdm_identifier: str
+    created_at: str
+    updated_at: str
+    runs_on_mac: bool = False
+    runs_on_iphone: bool = False
+    runs_on_ipad: bool = False
+    runs_on_tv: bool = False
+    runs_on_vision: bool = False
+
+
+class CustomScriptPayload(BaseModel):
+    """Payload model for custom script API endpoints."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: Annotated[str, AfterValidator(lambda value: value.lower())]
+    name: str
+    active: bool
+    execution_frequency: str
+    restart: bool
+    script: str
+    remediation_script: str
+    created_at: str
+    updated_at: str
+    show_in_self_service: bool
+    self_service_category_id: str | None = None
+    self_service_recommended: bool | None = None
+
+
+class SelfServiceCategoryPayload(BaseModel):
+    """Payload model for self-service categories API endpoints."""
+
+    id: str
+    name: str
+
+
+class PayloadList(BaseModel, Generic[ApiPayloadType]):
+    """Payload model for the syncable list endpoints."""
+
+    count: int = 0
+    next: str | None = None
+    previous: str | None = None
+    results: list[ApiPayloadType] = []

kst/api/profiles.py

@@ -0,0 +1,230 @@
+from io import BufferedReader
+from pathlib import Path
+
+from .payload import CustomProfilePayload, PayloadList
+from .resource_base import ResourceBase
+
+
+class CustomProfilesResource(ResourceBase):
+    """An API client wrapper for interacting with the Custom Profiles endpoint.
+
+    Attributes:
+        client (ApiClient): An ApiClient object with an open Session
+
+    Methods:
+        list: Retrieve a list of all custom profile(s)
+        get: Retrieve a single custom profile by id
+        create: Create a new custom profile
+        update: Update an existing custom profile by id
+        delete: Delete an existing custom profile by id
+
+    """
+
+    _path = "/api/v1/library/custom-profiles"
+
+    def list(self) -> PayloadList[CustomProfilePayload]:
+        """Retrieve a list of all custom profile(s).
+
+        Returns:
+            PayloadList: An object containing all combined results
+
+        Raises:
+            ApiClientError: Raised if a ApiClient has not been opened
+            HTTPError: Raised when the HTTP request returns an unsuccessful status code
+            ConnectionError: Raised when the API connection fails
+            ValidationError: Raised when the response does not match the expected schema
+
+        """
+
+        all_results = PayloadList[CustomProfilePayload]()
+        next_page = self._path
+        while next_page:
+            response = self.client.get(next_page)
+
+            # Parse bytes content to CustomProfilePayloadList or raise ValidationError
+            profile_list = PayloadList.model_validate_json(response.content)
+
+            all_results.count = profile_list.count
+            all_results.results.extend(profile_list.results)
+
+            next_page = profile_list.next
+
+        return all_results
+
+    def get(self, id: str) -> CustomProfilePayload:
+        """Retrieve details about a custom profile.
+
+        Args:
+            id (str): The library item id of the profile to retrieve
+
+        Returns:
+            CustomProfilePayload: A parsed object from the response
+
+        Raises:
+            ApiClientError: Raised if a ApiClient has not been opened
+            HTTPError: Raised when the HTTP request returns an unsuccessful status code
+            ConnectionError: Raised when the API connection fails
+            ValidationError: Raised when the response does not match the expected schema
+
+        """
+
+        response = self.client.get(f"{self._path}/{id}")
+        return CustomProfilePayload.model_validate_json(response.content)
+
+    def create(
+        self,
+        name: str,
+        file: Path | BufferedReader,
+        active: bool = False,
+        runs_on_mac: bool | None = None,
+        runs_on_iphone: bool | None = None,
+        runs_on_ipad: bool | None = None,
+        runs_on_tv: bool | None = None,
+        runs_on_vision: bool | None = None,
+    ) -> CustomProfilePayload:
+        """Create custom profiles in Kandji.
+
+        Args:
+            name (str): The name for the new profile
+            file (Path | BufferedReader): Path or open Buffer to the mobileconfig file to upload
+            active (bool): Whether the profile is active or not
+            runs_on_mac (bool): Whether the profile runs on macOS
+            runs_on_iphone (bool): Whether the profile runs on iPhone
+            runs_on_ipad (bool): Whether the profile runs on iPad
+            runs_on_tv (bool): Whether the profile runs on Apple TV
+            runs_on_vision (bool): Whether the profile runs on Apple TV
+
+        Returns:
+            CustomProfilePayload: A parsed object from the response
+
+        Raises:
+            ValueError: Raised when invalid parameters are passed
+            ApiClientError: Raised if a ApiClient has not been opened
+            HTTPError: Raised when the HTTP request returns an unsuccessful status code
+            ConnectionError: Raised when the API connection fails
+            ValidationError: Raised when the response does not match the expected schema
+
+        """
+
+        runs_on_args = {
+            "runs_on_mac": runs_on_mac,
+            "runs_on_iphone": runs_on_iphone,
+            "runs_on_ipad": runs_on_ipad,
+            "runs_on_tv": runs_on_tv,
+            "runs_on_vision": runs_on_vision,
+        }
+        if not any(runs_on_args.values()):
+            raise ValueError("At least one runs_on_* argument must be True.")
+
+        close_file = False
+        if isinstance(file, Path):
+            if not file.is_file():
+                raise FileNotFoundError(f"The file {file} does not exist or is not readable")
+            file_obj = file.open("rb")
+            file_name = file.name
+            close_file = True
+        elif isinstance(file, BufferedReader):
+            file_obj = file
+            file_name = f"{name}.mobileconfig"
+        else:
+            raise ValueError("Invalid file type provided. Must be a Path or BufferedReader object.")
+
+        files = [("file", (file_name, file_obj, "application/octet-stream"))]
+        payload = {"name": name, "active": active} | {k: v for k, v in runs_on_args.items() if v is not None}
+        response = self.client.post(self._path, data=payload, files=files)
+
+        if close_file:
+            file_obj.close()
+
+        return CustomProfilePayload.model_validate_json(response.content)
+
+    def update(
+        self,
+        id: str,
+        name: str | None = None,
+        file: Path | BufferedReader | None = None,
+        active: bool = False,
+        runs_on_mac: bool | None = None,
+        runs_on_iphone: bool | None = None,
+        runs_on_ipad: bool | None = None,
+        runs_on_tv: bool | None = None,
+        runs_on_vision: bool | None = None,
+    ) -> CustomProfilePayload:
+        """Update specified custom profile in Kandji with contents from provided .mobileconfig file in the specified directory.
+
+        Args:
+            id (str): The id of the profile to update
+            name (str): The name for the profile
+            file (Path | BufferedReader): Path or open Buffer to the mobileconfig file to upload
+            active (bool): Whether the profile is active or not
+            runs_on_mac (bool): Whether the profile runs on macOS
+            runs_on_iphone (bool): Whether the profile runs on iPhone
+            runs_on_ipad (bool): Whether the profile runs on iPad
+            runs_on_tv (bool): Whether the profile runs on Apple TV
+            runs_on_vision (bool): Whether the profile runs on Apple TV
+
+        Returns:
+            CustomProfilePayload: A parsed object from the response
+
+        Raises:
+            ValueError: Raised when invalid parameters are passed
+            ApiClientError: Raised if a ApiClient has not been opened
+            HTTPError: Raised when the HTTP request returns an unsuccessful status code
+            ConnectionError: Raised when the API connection fails
+            ValidationError: Raised when the response does not match the expected schema
+
+        """
+
+        payload = {
+            k: v
+            for k, v in {
+                "name": name,
+                "active": active,
+                "runs_on_mac": runs_on_mac,
+                "runs_on_iphone": runs_on_iphone,
+                "runs_on_ipad": runs_on_ipad,
+                "runs_on_tv": runs_on_tv,
+                "runs_on_vision": runs_on_vision,
+            }.items()
+            if v is not None
+        }
+
+        close_file = False
+        if file is not None:
+            if isinstance(file, Path):
+                if not file.is_file():
+                    raise FileNotFoundError(f"The file {file} does not exist or is not readable")
+                file_obj = file.open("rb")
+                file_name = file.name
+                close_file = True
+            elif isinstance(file, BufferedReader):
+                file_obj = file
+                file_name = f"{name if name is not None else id}.mobileconfig"
+            else:
+                raise ValueError("Invalid file type provided. Must be a Path or BufferedReader object.")
+            files = [("file", (file_name, file_obj, "application/octet-stream"))] if file else None
+        else:
+            files = None
+            file_obj = None
+
+        response = self.client.patch(f"{self._path}/{id}", data=payload, files=files)
+
+        if close_file and file_obj is not None:
+            file_obj.close()
+
+        return CustomProfilePayload.model_validate_json(response.content)
+
+    def delete(self, id: str) -> None:
+        """Delete specified custom profile in Kandji.
+
+        Args:
+            id (str): The id of the profile to delete
+
+        Raises:
+            ApiClientError: Raised if a ApiClient has not been opened
+            HTTPError: Raised when the HTTP request returns an unsuccessful status code
+            ConnectionError: Raised when the API connection fails
+
+        """
+
+        self.client.delete(f"{self._path}/{id}")

kst/api/resource_base.py

@@ -0,0 +1,57 @@
+from contextlib import AbstractContextManager
+from typing import Protocol, Self, override
+
+from kst.exceptions import ApiClientError
+
+from .client import ApiClient, ApiConfig
+
+
+class ResourceBase(AbstractContextManager, Protocol):
+    """An API client wrapper for interacting with the resource endpoints
+
+    Attributes:
+        client (ApiClient): An ApiClient object with an open Session
+
+    """
+
+    _path: str = ""
+    _config: ApiConfig
+    _client: ApiClient | None = None
+
+    def __init__(self, config: ApiConfig) -> None:
+        """Initialize a new CustomProfilesResource obj.
+
+        Args:
+            config (ApiConfig): An ApiConfig object with necessary configuration
+            path (str): The path to the resource endpoint
+
+        """
+        self._config = config
+        self._client: ApiClient | None = None
+
+    @property
+    def client(self) -> ApiClient:
+        if self._client is None:
+            raise ApiClientError("No open client available.")
+
+        return self._client
+
+    @override
+    def __enter__(self) -> Self:
+        """Open a new ApiClient session using with block and return self."""
+        self._client = ApiClient(self._config)
+        return self
+
+    @override
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        """Disconnect the ApiClient session when exiting the with block."""
+        self.client.close()
+        self._client = None
+
+    def open(self) -> None:
+        """Manually open a new ApiClient session."""
+        self.__enter__()
+
+    def close(self) -> None:
+        """Manually disconnect the ApiClient session."""
+        self.__exit__(None, None, None)