bt-cli 0.4.13__py3-none-any.whl

bt_cli/core/errors.py

@@ -0,0 +1,247 @@
+"""Centralized error handling for bt-cli CLI.
+
+Provides:
+- Error message sanitization to prevent credential leakage
+- HTTP status code to user-friendly message mapping
+- Consistent error formatting across all products
+"""
+
+import json
+import logging
+import re
+from typing import Any, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Patterns to sanitize from error messages
+# Each pattern captures a prefix group and replaces the sensitive value
+SENSITIVE_PATTERNS = [
+    # Bearer tokens (entire token after "Bearer ")
+    (r"(Bearer\s+)[A-Za-z0-9\-._~+/]+=*", r"\1[REDACTED]"),
+    # API keys in various formats
+    (r"(api[_-]?key[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    (r"(apikey[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    # Client secrets
+    (r"(client[_-]?secret[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    # Passwords
+    (r"(password[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    # Generic tokens
+    (r"(token[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    # Authorization headers - capture everything after colon/equals (including spaces)
+    (r"(authorization[=:]\s*).+", r"\1[REDACTED]"),
+    # PS-Auth header values
+    (r"(PS-Auth[=:]\s*)[^\s&\"']+", r"\1[REDACTED]"),
+    # Basic auth in URLs
+    (r"(://[^:]+:)[^@]+(@)", r"\1[REDACTED]\2"),
+]
+
+# Fields to redact in JSON structures (case-insensitive)
+SENSITIVE_FIELDS = {
+    "password", "secret", "token", "api_key", "apikey", "api-key",
+    "client_secret", "client-secret", "clientsecret",
+    "authorization", "bearer", "credential", "credentials",
+    "access_token", "refresh_token", "id_token", "session_token",
+    "private_key", "privatekey", "ssh_key", "sshkey",
+}
+
+
+def _sanitize_dict(data: Any, depth: int = 0, max_depth: int = 10) -> Any:
+    """Recursively sanitize sensitive fields in a dictionary.
+
+    Args:
+        data: Data structure to sanitize (dict, list, or primitive)
+        depth: Current recursion depth
+        max_depth: Maximum recursion depth to prevent infinite loops
+
+    Returns:
+        Sanitized data structure
+    """
+    if depth > max_depth:
+        return "[TRUNCATED - max depth]"
+
+    if isinstance(data, dict):
+        sanitized = {}
+        for key, value in data.items():
+            key_lower = str(key).lower().replace("-", "_").replace(" ", "_")
+            # Check if field name contains any sensitive pattern
+            if any(s in key_lower for s in SENSITIVE_FIELDS):
+                sanitized[key] = "[REDACTED]"
+            else:
+                sanitized[key] = _sanitize_dict(value, depth + 1, max_depth)
+        return sanitized
+    elif isinstance(data, list):
+        return [_sanitize_dict(item, depth + 1, max_depth) for item in data]
+    elif isinstance(data, str):
+        # Apply regex patterns to string values
+        return sanitize_error_message(data)
+    else:
+        return data
+
+
+def sanitize_error_message(message: str) -> str:
+    """Remove sensitive data from error messages.
+
+    Scans the message for patterns that may contain credentials,
+    tokens, or other sensitive information and replaces them.
+
+    Args:
+        message: The error message to sanitize
+
+    Returns:
+        Sanitized message with sensitive data replaced
+    """
+    if not message:
+        return message
+
+    result = message
+    for pattern, replacement in SENSITIVE_PATTERNS:
+        result = re.sub(pattern, replacement, result, flags=re.IGNORECASE)
+
+    return result
+
+
+# HTTP status code to user-friendly message mapping
+HTTP_STATUS_MESSAGES = {
+    400: "Bad request - the server could not understand the request",
+    401: "Authentication failed - check your credentials",
+    403: "Access denied - insufficient permissions for this operation",
+    404: "Resource not found",
+    405: "Method not allowed",
+    408: "Request timeout - the server took too long to respond",
+    409: "Conflict - the resource may already exist or be in use",
+    410: "Resource no longer available",
+    422: "Invalid data - the server could not process the request",
+    429: "Too many requests - please wait and try again",
+    500: "Internal server error",
+    502: "Bad gateway - the server received an invalid response",
+    503: "Service unavailable - the server is temporarily overloaded",
+    504: "Gateway timeout - the server took too long to respond",
+}
+
+
+def get_http_error_message(error: httpx.HTTPStatusError) -> str:
+    """Map HTTP status error to user-friendly message.
+
+    Args:
+        error: The HTTP status error from httpx
+
+    Returns:
+        User-friendly error message
+    """
+    status_code = error.response.status_code
+
+    # Get base message for status code
+    base_message = HTTP_STATUS_MESSAGES.get(
+        status_code, f"HTTP error {status_code}"
+    )
+
+    # Try to extract additional detail from response body
+    detail = None
+    try:
+        response_json = error.response.json()
+        # Deep sanitize the entire response to catch nested credentials
+        sanitized_response = _sanitize_dict(response_json)
+
+        # Common error detail field names across different APIs
+        for field in ["message", "error", "detail", "Message", "Error", "Description"]:
+            if field in sanitized_response:
+                value = sanitized_response[field]
+                # Handle nested error objects
+                if isinstance(value, dict):
+                    detail = value.get("message") or str(value)
+                else:
+                    detail = str(value)
+                break
+        # Handle nested error objects as fallback
+        if not detail and "error" in sanitized_response:
+            err = sanitized_response["error"]
+            if isinstance(err, dict):
+                detail = err.get("message")
+            elif isinstance(err, str):
+                detail = err
+    except Exception:
+        # Response may not be JSON
+        pass
+
+    if detail:
+        # Additional regex sanitization for any patterns in the extracted detail
+        detail = sanitize_error_message(str(detail))
+        return f"{base_message}: {detail}"
+
+    return base_message
+
+
+def get_connection_error_message(error: httpx.RequestError) -> str:
+    """Map connection/request error to user-friendly message.
+
+    Args:
+        error: The request error from httpx
+
+    Returns:
+        User-friendly error message
+    """
+    error_type = type(error).__name__
+    error_str = str(error)
+
+    # Sanitize the error string
+    error_str = sanitize_error_message(error_str)
+
+    # Check specific timeout types first (before generic TimeoutException)
+    if isinstance(error, httpx.ConnectTimeout):
+        return "Connection timed out - could not reach the server"
+    elif isinstance(error, httpx.ReadTimeout):
+        return "Read timed out - the server stopped responding"
+    elif isinstance(error, httpx.WriteTimeout):
+        return "Write timed out - could not send data to server"
+    elif isinstance(error, httpx.PoolTimeout):
+        return "Connection pool exhausted - too many concurrent requests"
+    elif isinstance(error, httpx.TimeoutException):
+        return "Request timed out - the server took too long to respond"
+    elif isinstance(error, httpx.ConnectError):
+        return "Could not connect to server - check the URL and network connection"
+    else:
+        # Generic request error
+        return f"Request failed: {error_str}"
+
+
+def handle_api_error(error: Exception, operation: str) -> str:
+    """Generate sanitized, contextual error message for API errors.
+
+    This is the main entry point for error handling. It determines
+    the error type and generates an appropriate user-friendly message.
+
+    Args:
+        error: The exception that occurred
+        operation: Description of the operation that failed (e.g., "list systems")
+
+    Returns:
+        User-friendly error message suitable for display
+    """
+    # Log full error for debugging
+    logger.debug(f"Error during '{operation}': {error}", exc_info=True)
+
+    if isinstance(error, httpx.HTTPStatusError):
+        message = get_http_error_message(error)
+        return f"Failed to {operation}: {message}"
+
+    elif isinstance(error, httpx.RequestError):
+        message = get_connection_error_message(error)
+        return f"Failed to {operation}: {message}"
+
+    elif isinstance(error, ValueError):
+        # Configuration or validation errors
+        sanitized = sanitize_error_message(str(error))
+        return f"Configuration error: {sanitized}"
+
+    elif isinstance(error, FileNotFoundError):
+        return f"Failed to {operation}: File not found"
+
+    elif isinstance(error, PermissionError):
+        return f"Failed to {operation}: Permission denied"
+
+    else:
+        # Generic error - sanitize the message
+        sanitized = sanitize_error_message(str(error))
+        return f"Failed to {operation}: {sanitized}"

bt_cli/core/output.py

@@ -0,0 +1,205 @@
+"""Shared output formatting utilities for BeyondTrust CLI."""
+
+import json
+from enum import Enum
+from typing import Any, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from .errors import handle_api_error
+
+
+class OutputFormat(str, Enum):
+    """Output format for CLI commands."""
+
+    TABLE = "table"
+    JSON = "json"
+
+
+# Shared console instance
+console = Console()
+
+
+def print_json(data: Any) -> None:
+    """Print data as formatted JSON.
+
+    Args:
+        data: Any JSON-serializable data
+    """
+    console.print_json(json.dumps(data, indent=2, default=str))
+
+
+def print_table(
+    data: list[dict[str, Any]],
+    columns: list[tuple[str, str]],
+    title: Optional[str] = None,
+    show_header: bool = True,
+) -> None:
+    """Print data as a rich table.
+
+    Args:
+        data: List of dictionaries to display
+        columns: List of (display_name, key) tuples defining columns
+        title: Optional table title
+        show_header: Whether to show column headers
+    """
+    if not data:
+        console.print("[dim]No results found[/dim]")
+        return
+
+    table = Table(title=title, show_header=show_header, header_style="bold cyan")
+
+    # Add columns
+    for display_name, _ in columns:
+        table.add_column(display_name)
+
+    # Add rows
+    for item in data:
+        row = []
+        for _, key in columns:
+            val = _format_value(item.get(key))
+            row.append(val)
+        table.add_row(*row)
+
+    console.print(table)
+
+
+def print_detail(
+    data: dict[str, Any],
+    fields: list[tuple[str, str]],
+    title: Optional[str] = None,
+) -> None:
+    """Print detailed view of a single item.
+
+    Args:
+        data: Dictionary containing item data
+        fields: List of (label, key) tuples for fields to display
+        title: Optional panel title
+    """
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    for label, key in fields:
+        value = data.get(key)
+        if value is not None:
+            table.add_row(label, _format_value(value))
+
+    if title:
+        console.print(Panel(table, title=title))
+    else:
+        console.print(table)
+
+
+def _format_value(value: Any) -> str:
+    """Format a value for display.
+
+    Args:
+        value: Value to format
+
+    Returns:
+        Formatted string representation
+    """
+    if value is None:
+        return "-"
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, dict):
+        # Try common nested object patterns
+        return str(
+            value.get("name")
+            or value.get("Name")
+            or value.get("id")
+            or value.get("Id")
+            or value.get("ID")
+            or json.dumps(value, default=str)
+        )
+    if isinstance(value, list):
+        if not value:
+            return "-"
+        # Format list items
+        formatted = []
+        for v in value[:3]:  # Limit to first 3
+            if isinstance(v, dict):
+                formatted.append(
+                    str(v.get("name") or v.get("Name") or v.get("id") or v)
+                )
+            else:
+                formatted.append(str(v))
+        result = ", ".join(formatted)
+        if len(value) > 3:
+            result += f" (+{len(value) - 3} more)"
+        return result
+    return str(value)
+
+
+def print_success(message: str) -> None:
+    """Print a success message.
+
+    Args:
+        message: Message to display
+    """
+    console.print(f"[green]{message}[/green]")
+
+
+def print_error(message: str) -> None:
+    """Print an error message.
+
+    Args:
+        message: Error message to display
+    """
+    console.print(f"[red]Error:[/red] {message}")
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message.
+
+    Args:
+        message: Warning message to display
+    """
+    console.print(f"[yellow]Warning:[/yellow] {message}")
+
+
+def print_info(message: str) -> None:
+    """Print an info message.
+
+    Args:
+        message: Info message to display
+    """
+    console.print(f"[blue]{message}[/blue]")
+
+
+def confirm_action(message: str, default: bool = False) -> bool:
+    """Prompt user for confirmation.
+
+    Args:
+        message: Confirmation prompt
+        default: Default value if user presses Enter
+
+    Returns:
+        True if confirmed, False otherwise
+    """
+    suffix = " [Y/n]" if default else " [y/N]"
+    response = console.input(f"{message}{suffix} ").strip().lower()
+
+    if not response:
+        return default
+    return response in ("y", "yes")
+
+
+def print_api_error(error: Exception, operation: str) -> None:
+    """Print a sanitized API error message with context.
+
+    Uses centralized error handling to:
+    - Map HTTP status codes to user-friendly messages
+    - Sanitize error messages to prevent credential leakage
+    - Provide consistent error formatting
+
+    Args:
+        error: The exception that occurred
+        operation: Description of the operation that failed (e.g., "list systems")
+    """
+    message = handle_api_error(error, operation)
+    console.print(f"[red]Error:[/red] {message}")

bt_cli/core/prompts.py

@@ -0,0 +1,87 @@
+"""Reusable interactive prompts for CLI commands."""
+
+from typing import Any, Callable, Optional, TypeVar
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+T = TypeVar("T")
+
+
+def prompt_if_missing(
+    value: Optional[T],
+    prompt_text: str,
+    value_type: type = str,
+) -> T:
+    """Prompt for a value if it's missing.
+
+    Args:
+        value: Current value (may be None)
+        prompt_text: Text to show in prompt
+        value_type: Type for typer.prompt (str, int, float)
+
+    Returns:
+        The value (either original or prompted)
+    """
+    if value is None or value == "":
+        return typer.prompt(prompt_text, type=value_type)
+    return value
+
+
+def prompt_from_list(
+    items: list[dict[str, Any]],
+    prompt_text: str,
+    id_key: str,
+    name_key: str,
+    title: str,
+    value_type: type = int,
+) -> Any:
+    """Show a list of items and prompt for selection.
+
+    Args:
+        items: List of dicts to display
+        prompt_text: Prompt text (e.g., "Workgroup ID")
+        id_key: Key for the ID field in each dict
+        name_key: Key for the display name field
+        title: Title to show above list
+        value_type: Type of the ID (int or str)
+
+    Returns:
+        The selected ID
+    """
+    console.print(f"\n[bold]{title}:[/bold]")
+    for item in items:
+        item_id = item.get(id_key, "")
+        item_name = item.get(name_key, "Unknown")
+        console.print(f"  {item_id}: {item_name}")
+    return typer.prompt(prompt_text, type=value_type)
+
+
+def prompt_choice(
+    prompt_text: str,
+    choices: list[tuple[str, str]],
+    default: Optional[str] = None,
+) -> str:
+    """Prompt for a choice from a list of options.
+
+    Args:
+        prompt_text: Text to show
+        choices: List of (value, description) tuples
+        default: Default value
+
+    Returns:
+        The selected value
+    """
+    console.print(f"\n[bold]{prompt_text}:[/bold]")
+    for value, desc in choices:
+        marker = " (default)" if value == default else ""
+        console.print(f"  {value}: {desc}{marker}")
+
+    result = typer.prompt("Choice", default=default or choices[0][0])
+    valid_values = [v for v, _ in choices]
+    while result not in valid_values:
+        console.print(f"[red]Invalid choice. Options: {', '.join(valid_values)}[/red]")
+        result = typer.prompt("Choice", default=default or choices[0][0])
+    return result