bt-cli 0.4.13__py3-none-any.whl

bt_cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core shared utilities for BeyondTrust CLI."""

bt_cli/core/auth.py

@@ -0,0 +1,213 @@
+"""Authentication strategies for BeyondTrust products."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class AuthStrategy(ABC):
+    """Base class for authentication strategies.
+
+    Each product may use different authentication mechanisms.
+    This abstraction allows the base client to work with any auth method.
+    """
+
+    @abstractmethod
+    def get_headers(self) -> dict[str, str]:
+        """Get authentication headers for requests.
+
+        Returns:
+            Dictionary of headers to include in requests
+        """
+        pass
+
+    def authenticate(self, client: httpx.Client) -> dict:
+        """Perform any initial authentication if needed.
+
+        Some auth methods (like OAuth) require an initial token exchange.
+        Others (like API key) don't need this step.
+
+        Args:
+            client: HTTP client to use for auth requests
+
+        Returns:
+            Authentication response data (may be empty dict)
+        """
+        return {}
+
+    def sign_out(self, client: httpx.Client) -> None:
+        """Perform any cleanup/sign-out if needed.
+
+        Args:
+            client: HTTP client to use for sign-out
+        """
+        pass
+
+
+class BearerTokenAuth(AuthStrategy):
+    """Simple Bearer token authentication.
+
+    Used by: Entitle
+
+    The API key is passed directly as a Bearer token.
+    No session management required.
+    """
+
+    def __init__(self, api_key: str):
+        """Initialize with API key.
+
+        Args:
+            api_key: API key to use as Bearer token
+        """
+        self.api_key = api_key
+
+    def __repr__(self) -> str:
+        """Safe repr that doesn't expose credentials."""
+        return f"BearerTokenAuth(api_key='***')"
+
+    def get_headers(self) -> dict[str, str]:
+        """Get Bearer auth header."""
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+
+class PSAuthKeyAuth(AuthStrategy):
+    """PS-Auth header authentication for Password Safe.
+
+    Used by: Password Safe (API key method)
+
+    Uses custom PS-Auth header format with optional impersonation.
+    Requires session establishment via SignAppIn.
+    """
+
+    def __init__(self, api_key: str, run_as: Optional[str] = None):
+        """Initialize with API key and optional impersonation.
+
+        Args:
+            api_key: API key for authentication
+            run_as: Optional username for impersonation
+        """
+        self.api_key = api_key
+        self.run_as = run_as
+        self._session_active = False
+
+    def __repr__(self) -> str:
+        """Safe repr that doesn't expose credentials."""
+        run_as_str = f", run_as='{self.run_as}'" if self.run_as else ""
+        return f"PSAuthKeyAuth(api_key='***'{run_as_str})"
+
+    def get_headers(self) -> dict[str, str]:
+        """Get PS-Auth header with optional runas."""
+        auth_value = f"PS-Auth key={self.api_key};"
+        if self.run_as:
+            auth_value += f" runas={self.run_as};"
+        return {"Authorization": auth_value}
+
+    def authenticate(self, client: httpx.Client) -> dict:
+        """Establish session via SignAppIn.
+
+        Args:
+            client: HTTP client configured with base URL
+
+        Returns:
+            Session info from SignAppIn response
+        """
+        headers = self.get_headers()
+        headers["Content-Type"] = "application/json"
+
+        response = client.post("/Auth/SignAppIn", headers=headers)
+        response.raise_for_status()
+        self._session_active = True
+        return response.json()
+
+    def sign_out(self, client: httpx.Client) -> None:
+        """Sign out and end session."""
+        if self._session_active:
+            try:
+                headers = self.get_headers()
+                headers["Content-Type"] = "application/json"
+                client.post("/Auth/Signout", headers=headers)
+            except Exception as e:
+                logger.debug(f"Sign out failed (best effort): {e}")
+            finally:
+                self._session_active = False
+
+
+class OAuthClientCredentials(AuthStrategy):
+    """OAuth client credentials flow for Password Safe.
+
+    Used by: Password Safe (OAuth method)
+
+    Exchanges client_id/client_secret for access token,
+    then uses Bearer token for subsequent requests.
+    """
+
+    def __init__(self, client_id: str, client_secret: str):
+        """Initialize with OAuth credentials.
+
+        Args:
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+        """
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._access_token: Optional[str] = None
+        self._session_active = False
+
+    def __repr__(self) -> str:
+        """Safe repr that doesn't expose credentials."""
+        return f"OAuthClientCredentials(client_id='{self.client_id}', client_secret='***')"
+
+    def get_headers(self) -> dict[str, str]:
+        """Get Bearer auth header with access token."""
+        if self._access_token:
+            return {"Authorization": f"Bearer {self._access_token}"}
+        return {}
+
+    def authenticate(self, client: httpx.Client) -> dict:
+        """Exchange credentials for token and establish session.
+
+        Args:
+            client: HTTP client configured with base URL
+
+        Returns:
+            Session info from SignAppIn response
+        """
+        # Step 1: Get access token
+        token_response = client.post(
+            "/Auth/connect/token",
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        token_response.raise_for_status()
+        token_data = token_response.json()
+        self._access_token = token_data.get("access_token")
+
+        # Step 2: Establish session
+        headers = self.get_headers()
+        headers["Content-Type"] = "application/json"
+
+        session_response = client.post("/Auth/SignAppIn", headers=headers)
+        session_response.raise_for_status()
+        self._session_active = True
+        return session_response.json()
+
+    def sign_out(self, client: httpx.Client) -> None:
+        """Sign out and end session."""
+        if self._session_active:
+            try:
+                headers = self.get_headers()
+                headers["Content-Type"] = "application/json"
+                client.post("/Auth/Signout", headers=headers)
+            except Exception as e:
+                logger.debug(f"Sign out failed (best effort): {e}")
+            finally:
+                self._session_active = False
+                self._access_token = None

bt_cli/core/client.py

@@ -0,0 +1,313 @@
+"""Base HTTP client for BeyondTrust products."""
+
+import logging
+import os
+import sys
+from typing import Any, Optional
+
+import httpx
+
+from .auth import AuthStrategy
+
+logger = logging.getLogger(__name__)
+
+# Track if SSL warning has been shown (only show once per process)
+_ssl_warning_shown = False
+
+
+def _warn_ssl_disabled() -> None:
+    """Print warning to stderr when SSL verification is disabled.
+
+    Security: SSL verification protects against man-in-the-middle attacks.
+    Disabling it allows attackers to intercept credentials and data.
+
+    Only shows detailed warning once per process, but logs every time.
+    Suppression requires explicit BT_SSL_INSECURE_ALLOW=1 (not just any value).
+    """
+    global _ssl_warning_shown
+
+    # Always log for audit trail
+    logger.warning("SSL certificate verification is DISABLED - connection is insecure")
+
+    # Check for explicit opt-in to suppress visual warning
+    # Requires explicit value "1" to prevent accidental suppression
+    if os.environ.get("BT_SSL_INSECURE_ALLOW") == "1":
+        if not _ssl_warning_shown:
+            _ssl_warning_shown = True
+            print(
+                "\033[93m[SSL WARNING SUPPRESSED - BT_SSL_INSECURE_ALLOW=1]\033[0m",
+                file=sys.stderr,
+            )
+        return
+
+    if _ssl_warning_shown:
+        return
+
+    _ssl_warning_shown = True
+    print(
+        "\n\033[91m" + "=" * 70 + "\n"
+        "SECURITY WARNING: SSL certificate verification is DISABLED\n"
+        "=" * 70 + "\033[0m\n"
+        "\033[93m"
+        "This exposes your credentials to man-in-the-middle attacks.\n"
+        "Only use for testing with self-signed certificates.\n"
+        "\n"
+        "To suppress this warning (NOT RECOMMENDED):\n"
+        "  export BT_SSL_INSECURE_ALLOW=1\n"
+        "\033[0m",
+        file=sys.stderr,
+    )
+
+
+class BaseClient:
+    """Base HTTP client that all product clients inherit from.
+
+    Provides common functionality:
+    - Context manager for connection lifecycle
+    - Request methods (GET, POST, PUT, DELETE)
+    - Response handling
+    - Auth integration
+
+    Product clients extend this with:
+    - Product-specific auth configuration
+    - Pagination handling (varies by API)
+    - Convenience methods for API endpoints
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth: AuthStrategy,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+    ):
+        """Initialize base client.
+
+        Args:
+            base_url: API base URL
+            auth: Authentication strategy to use
+            timeout: Request timeout in seconds
+            verify_ssl: Whether to verify SSL certificates
+        """
+        self.base_url = base_url.rstrip("/")
+        self.auth = auth
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+        self._client: Optional[httpx.Client] = None
+
+    def _ensure_client(self) -> httpx.Client:
+        """Ensure HTTP client is initialized.
+
+        Returns:
+            The httpx client
+
+        Raises:
+            RuntimeError: If client not initialized (not in context manager)
+        """
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Use as context manager: "
+                "'with get_client() as client:'"
+            )
+        return self._client
+
+    def __enter__(self) -> "BaseClient":
+        """Enter context manager - create HTTP client."""
+        if not self.verify_ssl:
+            _warn_ssl_disabled()
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            verify=self.verify_ssl,
+        )
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context manager - close HTTP client."""
+        if self._client:
+            self._client.close()
+            self._client = None
+
+    def _get_headers(self) -> dict[str, str]:
+        """Build request headers including auth.
+
+        Returns:
+            Headers dictionary with content type and auth
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        headers.update(self.auth.get_headers())
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        files: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API endpoint path
+            params: Query parameters
+            json: JSON body (for POST/PUT)
+            data: Form data (for POST)
+            headers: Additional headers
+            files: File upload data
+
+        Returns:
+            Parsed JSON response, or empty dict for 204/empty responses
+
+        Raises:
+            httpx.HTTPStatusError: If request fails
+        """
+        client = self._ensure_client()
+
+        # Build headers
+        request_headers = self._get_headers()
+        if headers:
+            request_headers.update(headers)
+
+        # Handle file uploads - don't send Content-Type, let httpx set it
+        if files:
+            request_headers.pop("Content-Type", None)
+
+        # Filter out None params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = client.request(
+            method=method,
+            url=path,
+            params=params,
+            json=json,
+            data=data,
+            headers=request_headers,
+            files=files,
+        )
+        response.raise_for_status()
+
+        # Handle empty responses
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        # Try to parse JSON
+        try:
+            return response.json()
+        except Exception:
+            return {"content": response.text}
+
+    def get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make a GET request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Parsed JSON response
+        """
+        return self._request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        files: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make a POST request.
+
+        Args:
+            path: API endpoint path
+            json: JSON body
+            data: Form data
+            headers: Additional headers
+            files: File upload data
+
+        Returns:
+            Parsed JSON response
+        """
+        return self._request(
+            "POST", path, json=json, data=data, headers=headers, files=files
+        )
+
+    def put(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        files: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make a PUT request.
+
+        Args:
+            path: API endpoint path
+            json: JSON body
+            data: Form data
+            headers: Additional headers
+            files: File upload data
+
+        Returns:
+            Parsed JSON response
+        """
+        return self._request(
+            "PUT", path, json=json, data=data, headers=headers, files=files
+        )
+
+    def delete(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make a DELETE request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Parsed JSON response
+        """
+        return self._request("DELETE", path, params=params)
+
+    def get_raw(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> bytes:
+        """Make a GET request and return raw bytes.
+
+        Useful for file downloads.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Raw response bytes
+        """
+        client = self._ensure_client()
+        headers = self._get_headers()
+        headers.pop("Content-Type", None)  # Not needed for downloads
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = client.get(path, params=params, headers=headers)
+        response.raise_for_status()
+        return response.content