nac-test-pyats-common 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

nac_test_pyats_common/catc/auth.py

@@ -14,14 +14,21 @@ The module implements a two-tier API design:
 
 This design ensures efficient token management by reusing valid tokens and only
 re-authenticating when necessary, reducing unnecessary API calls to the controller.
+
+Note on Fork Safety:
+    This module uses urllib instead of httpx for synchronous authentication requests.
+    httpx is NOT fork-safe on macOS - creating httpx.Client after fork() causes
+    silent crashes due to OpenSSL threading issues. urllib uses simpler primitives
+    that work correctly after fork().
 """
 
 import os
 from typing import Any
 
-import httpx
-from nac_test.pyats_core.common.auth_cache import (
-    AuthCache,  # type: ignore[import-untyped]
+from nac_test.pyats_core.common.auth_cache import AuthCache
+from nac_test.pyats_core.common.subprocess_auth import (
+    SubprocessAuthError,  # noqa: F401 - re-exported for callers to catch
+    execute_auth_subprocess,
 )
 
 # Default token lifetime for Catalyst Center authentication in seconds
@@ -74,6 +81,10 @@ class CatalystCenterAuth:
         using Basic Auth. It tries the modern auth endpoint first, then falls back
         to the legacy endpoint if needed for backward compatibility.
 
+        Note: On macOS, SSL operations in forked processes crash due to OpenSSL
+        threading issues. This method uses subprocess with spawn context to perform
+        authentication in a fresh process, avoiding the fork+SSL crash.
+
         Args:
             url: Base URL of the Catalyst Center (e.g., "https://catc.example.com").
                 Should not include trailing slashes or API paths.
@@ -90,56 +101,110 @@ class CatalystCenterAuth:
                 - expires_in (int): Token lifetime in seconds (typically 3600).
 
         Raises:
-            httpx.HTTPStatusError: If Catalyst Center returns a non-2xx status code
-                on all auth endpoints, typically indicating authentication failure.
-            RuntimeError: If authentication fails on all available endpoints.
-            ValueError: If the token is not received in the response from any endpoint.
+            SubprocessAuthError: If authentication subprocess fails or authentication
+                fails on all available endpoints.
+            ValueError: If the authentication response is malformed.
 
         Note:
             SSL verification can be disabled via the verify_ssl parameter to handle
             self-signed certificates commonly used in lab deployments. In production
             environments, proper certificate validation should be enabled.
         """
-        last_error: Exception | None = None
-
-        with httpx.Client(
-            verify=verify_ssl, timeout=AUTH_REQUEST_TIMEOUT_SECONDS
-        ) as client:
-            for endpoint in AUTH_ENDPOINTS:
-                try:
-                    auth_response = client.post(
-                        f"{url}{endpoint}",
-                        auth=(username, password),
-                        headers={
-                            "Content-Type": "application/json",
-                            "Accept": "application/json",
-                        },
-                    )
-                    auth_response.raise_for_status()
-
-                    # Extract token from response
-                    response_data = auth_response.json()
-                    token = response_data.get("Token")
-
-                    if not token:
-                        raise ValueError(
-                            f"No 'Token' field in auth response from {endpoint}. "
-                            f"Response keys: {list(response_data.keys())}"
-                        )
-
-                    # Return auth data with token lifetime
-                    return {"token": str(token)}, CATALYST_CENTER_TOKEN_LIFETIME_SECONDS
-
-                except (httpx.HTTPError, ValueError) as e:
-                    last_error = e
-                    # Try next endpoint
-                    continue
-
-            # All endpoints failed
-            raise RuntimeError(
-                f"Catalyst Center authentication failed on all endpoints. "
-                f"Last error: {last_error}"
-            ) from last_error
+        # Build auth parameters for subprocess
+        auth_params = {
+            "url": url,
+            "username": username,
+            "password": password,
+            "timeout": AUTH_REQUEST_TIMEOUT_SECONDS,
+            "verify_ssl": verify_ssl,
+            "endpoints": AUTH_ENDPOINTS,
+        }
+
+        # Catalyst Center-specific authentication logic
+        # This script assumes `params` dict is already loaded by execute_auth_subprocess
+        auth_script_body = """
+import base64
+import json
+import ssl
+import urllib.request
+import urllib.error
+
+url = params["url"]
+username = params["username"]
+password = params["password"]
+timeout = params["timeout"]
+verify_ssl = params["verify_ssl"]
+endpoints = params["endpoints"]
+
+# Create SSL context
+ssl_context = ssl.create_default_context()
+if not verify_ssl:
+    ssl_context.check_hostname = False
+    ssl_context.verify_mode = ssl.CERT_NONE
+
+# Create Basic Auth header
+credentials = f"{username}:{password}"
+b64_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
+auth_header = f"Basic {b64_credentials}"
+
+# Create HTTPS handler with SSL context
+https_handler = urllib.request.HTTPSHandler(context=ssl_context)
+opener = urllib.request.build_opener(https_handler)
+
+last_error = None
+
+for endpoint in endpoints:
+    try:
+        # Create request with Basic Auth and proper headers
+        request = urllib.request.Request(
+            f"{url}{endpoint}",
+            data=None,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Authorization": auth_header,
+            },
+            method="POST"
+        )
+
+        # Execute authentication request
+        response = opener.open(request, timeout=timeout)
+        response_body = response.read().decode("utf-8")
+        response_data = json.loads(response_body)
+
+        # Extract token from response
+        token = response_data.get("Token")
+        if not token:
+            raise ValueError(
+                f"No 'Token' field in auth response from {endpoint}. "
+                f"Response keys: {list(response_data.keys())}"
+            )
+
+        result = {"token": str(token)}
+        break  # Success - exit loop
+
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8") if e.fp else ""
+        err_snippet = error_body[:200]
+        last_error = (
+            f"HTTP {e.code} on {endpoint}: {e.reason}. {err_snippet}"
+        )
+        continue
+    except ValueError as e:
+        last_error = str(e)
+        continue
+    except Exception as e:
+        last_error = f"{endpoint}: {str(e)}"
+        continue
+else:
+    # Loop completed without break - all endpoints failed
+    result = {"error": f"All endpoints failed. Last error: {last_error}"}
+"""
+
+        # Execute authentication in subprocess (fork-safe on macOS)
+        auth_result = execute_auth_subprocess(auth_params, auth_script_body)
+
+        return {"token": auth_result["token"]}, CATALYST_CENTER_TOKEN_LIFETIME_SECONDS
 
     @classmethod
     def get_auth(cls) -> dict[str, Any]:
@@ -168,8 +233,10 @@ class CatalystCenterAuth:
         Raises:
             ValueError: If any required environment variables (CC_URL, CC_USERNAME,
                 CC_PASSWORD) are not set.
-            RuntimeError: If authentication fails on all available endpoints.
-            httpx.HTTPStatusError: If Catalyst Center returns authentication errors.
+            SubprocessAuthError: If authentication fails due to invalid credentials,
+                network issues, connection timeouts, or Catalyst Center server errors.
+                The error message will contain details from the authentication
+                subprocess.
 
         Example:
             >>> # Set environment variables first

nac_test_pyats_common/catc/device_resolver.py

@@ -141,16 +141,23 @@ class CatalystCenterDeviceResolver(BaseDeviceResolver):
 
         return ip_value
 
-    def extract_os_type(self, device_data: dict[str, Any]) -> str:
-        """Return 'iosxe' as all managed devices are IOS-XE based.
+    def extract_os_platform_type(self, device_data: dict[str, Any]) -> dict[str, str]:
+        """Return PyATS abstraction info for Catalyst Center managed devices.
+
+        All managed devices are currently IOS-XE based. Platform and model
+        could potentially be extracted from the 'pid' field in the future.
 
         Args:
-            device_data: Device data dictionary (unused, OS is hardcoded).
+            device_data: Device data dictionary from the data model.
 
         Returns:
-            Always returns 'iosxe'.
+            Dictionary with 'os' key (and potentially platform/model in future).
         """
-        return "iosxe"
+        return {
+            "os": "iosxe",
+            # Future enhancement: extract platform/model from pid field
+            # e.g., "C9300-24P" -> platform="cat9k", model="c9300"
+        }
 
     def get_credential_env_vars(self) -> tuple[str, str]:
         """Return IOS-XE credential env vars for managed devices.

nac_test_pyats_common/common/base_device_resolver.py

@@ -24,13 +24,17 @@ class BaseDeviceResolver(ABC):
     resolution. It handles common logic (credential injection, device dict
     construction) while delegating schema-specific work to abstract methods.
 
+    Credentials are injected as environment variable references (%ENV{VARNAME})
+    rather than cleartext values for security. PyATS testbed loader will resolve
+    these references at runtime.
+
     Subclasses MUST implement:
         - get_architecture_name(): Return architecture identifier (e.g., "sdwan")
         - get_schema_root_key(): Return the root key in data model (e.g., "sdwan")
         - navigate_to_devices(): Navigate schema to get iterable of device data
         - extract_hostname(): Extract hostname from device data
         - extract_host_ip(): Extract management IP from device data
-        - extract_os_type(): Extract OS type from device data
+        - extract_os_platform_type(): Extract OS and platform info from device data
         - get_credential_env_vars(): Return (username_env_var, password_env_var)
 
     Subclasses MAY override:
@@ -55,6 +59,8 @@ class BaseDeviceResolver(ABC):
         >>>
         >>> resolver = SDWANDeviceResolver(data_model)
         >>> devices = resolver.get_resolved_inventory()
+        >>> # devices[0]["username"] == "%ENV{IOSXE_USERNAME}"
+        >>> # devices[0]["password"] == "%ENV{IOSXE_PASSWORD}"
     """
 
     def __init__(self, data_model: dict[str, Any]) -> None:
@@ -75,7 +81,7 @@ class BaseDeviceResolver(ABC):
         1. Navigates the data model to find device data
         2. Extracts hostname and management IP from each device
         3. Sets OS type (architecture-specific, e.g., hardcoded to 'iosxe' for SD-WAN)
-        4. Injects SSH credentials from environment variables
+        4. Injects SSH credential environment variable references
         5. Returns list of device dicts ready for nac-test
 
         Returns:
@@ -83,8 +89,8 @@ class BaseDeviceResolver(ABC):
             - hostname (str)
             - host (str)
             - os (str)
-            - username (str)
-            - password (str)
+            - username (str): Environment variable reference in %ENV{VARNAME} format
+            - password (str): Environment variable reference in %ENV{VARNAME} format
             - Plus any architecture-specific fields
 
         Raises:
@@ -178,15 +184,16 @@ class BaseDeviceResolver(ABC):
             device_data: Raw device data from the data model.
 
         Returns:
-            Device dictionary with hostname, host, os, device_id fields.
-            Credentials are injected separately.
+            Device dictionary with hostname, host, os, device_id fields,
+            plus optional platform, model, series fields if provided by
+            extract_os_platform_type(). Credentials are injected separately.
 
         Raises:
             ValueError: If any required field extraction fails.
         """
         hostname = self.extract_hostname(device_data)
         host = self.extract_host_ip(device_data)
-        os_type = self.extract_os_type(device_data)
+        os_platform_info = self.extract_os_platform_type(device_data)
         device_id = self.extract_device_id(device_data)
 
         # Validate all extracted values are non-empty strings
@@ -203,18 +210,38 @@ class BaseDeviceResolver(ABC):
                 f"Invalid IP address format: '{host}'. "
                 "Ensure the field contains a valid IPv4 or IPv6 address."
             ) from None
+
+        # Validate os_platform_info structure
+        # Runtime check for dict type (defensive programming for non-mypy users)
+        if not isinstance(os_platform_info, dict):
+            type_name = type(os_platform_info).__name__  # type: ignore[unreachable]
+            raise ValueError(  # type: ignore[unreachable]
+                f"extract_os_platform_type must return a dict, got {type_name}"
+            )
+        if "os" not in os_platform_info:
+            raise ValueError("extract_os_platform_type must return dict with 'os' key")
+
+        os_type = os_platform_info["os"]
         if not isinstance(os_type, str) or not os_type:
             raise ValueError(f"Invalid OS type: {os_type!r}")
         if not isinstance(device_id, str) or not device_id:
             raise ValueError(f"Invalid device ID: {device_id!r}")
 
-        return {
+        # Build base device dict with required fields
+        device_dict = {
             "hostname": hostname,
             "host": host,
             "os": os_type,
             "device_id": device_id,
         }
 
+        # Add optional PyATS abstraction fields if present
+        for field in ["platform", "model", "series"]:
+            if field in os_platform_info:
+                device_dict[field] = os_platform_info[field]
+
+        return device_dict
+
     # -------------------------------------------------------------------------
     # Private helper methods
     # -------------------------------------------------------------------------
@@ -227,7 +254,15 @@ class BaseDeviceResolver(ABC):
             return "<unknown>"
 
     def _inject_credentials(self, devices: list[dict[str, Any]]) -> None:
-        """Inject SSH credentials from environment variables.
+        """Inject SSH credential environment variable references.
+
+        Injects credentials as %ENV{VARNAME} references instead of cleartext
+        values for security. PyATS testbed loader will resolve these at runtime.
+
+        This prevents credentials from being written to disk in testbed.yaml files.
+
+        If consumers need cleartext values, they can detect the %ENV{} pattern
+        and resolve via os.environ.get() themselves.
 
         Args:
             devices: List of device dicts to update in place.
@@ -236,14 +271,12 @@ class BaseDeviceResolver(ABC):
             ValueError: If required credential environment variables are not set.
         """
         username_var, password_var = self.get_credential_env_vars()
-        username = os.environ.get(username_var)
-        password = os.environ.get(password_var)
 
-        # FAIL FAST - raise error if credentials missing
+        # FAIL FAST - validate env vars are set (without reading values)
         missing_vars: list[str] = []
-        if not username:
+        if username_var not in os.environ:
             missing_vars.append(username_var)
-        if not password:
+        if password_var not in os.environ:
             missing_vars.append(password_var)
 
         if missing_vars:
@@ -253,10 +286,13 @@ class BaseDeviceResolver(ABC):
                 f"These are required for {self.get_architecture_name()} D2D testing."
             )
 
-        logger.debug(f"Injecting credentials from {username_var} and {password_var}")
+        # Inject environment variable references (not cleartext values)
+        logger.debug(
+            f"Injecting credential references for {username_var} and {password_var}"
+        )
         for device in devices:
-            device["username"] = username
-            device["password"] = password
+            device["username"] = f"%ENV{{{username_var}}}"
+            device["password"] = f"%ENV{{{password_var}}}"
 
     # -------------------------------------------------------------------------
     # Abstract methods - MUST be implemented by subclasses
@@ -363,18 +399,29 @@ class BaseDeviceResolver(ABC):
         ...
 
     @abstractmethod
-    def extract_os_type(self, device_data: dict[str, Any]) -> str:
-        """Extract operating system type from device data.
+    def extract_os_platform_type(self, device_data: dict[str, Any]) -> dict[str, str]:
+        """Extract PyATS device abstraction fields from device data.
+
+        Returns a dictionary with device abstraction information for PyATS:
+        - os (required): Operating system type (e.g., "iosxe", "nxos")
+        - platform (optional): Device platform (e.g., "sdwan", "cat9k")
+        - model (optional): Device model (e.g., "c8000v", "c9300")
+        - series (optional): Device series (e.g., "catalyst", "nexus")
 
         Args:
             device_data: Device data dict from navigate_to_devices().
 
         Returns:
-            OS type string (e.g., "iosxe", "nxos", "iosxr").
-
-        Example (SD-WAN):
-            >>> def extract_os_type(self, device_data):
-            ...     return device_data.get("os", "iosxe")
+            Dictionary containing at minimum the 'os' key, with optional
+            'platform', 'model', and 'series' keys.
+
+        Example:
+            >>> def extract_os_platform_type(self, device_data):
+            ...     return {
+            ...         "os": "iosxe",
+            ...         "platform": "sdwan",
+            ...         "model": "c8000v"  # if extractable
+            ...     }
         """
         ...
 

nac_test_pyats_common/iosxe/iosxe_resolver.py

@@ -56,8 +56,8 @@ class IOSXEResolver(BaseDeviceResolver):
         """Extract management IP."""
         raise NotImplementedError("IOSXEResolver is not yet implemented")
 
-    def extract_os_type(self, device_data: dict[str, Any]) -> str:
-        """Extract OS type."""
+    def extract_os_platform_type(self, device_data: dict[str, Any]) -> dict[str, str]:
+        """Extract OS and platform info."""
         raise NotImplementedError("IOSXEResolver is not yet implemented")
 
     def get_credential_env_vars(self) -> tuple[str, str]:

nac_test_pyats_common/sdwan/api_test_base.py

@@ -68,6 +68,7 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
     """
 
     client: httpx.AsyncClient | None = None  # MUST declare at class level
+    auth_data: dict[str, Any]  # Declared at class level for type checker compatibility
 
     @aetest.setup  # type: ignore[misc, untyped-decorator]
     def setup(self) -> None:
@@ -77,7 +78,11 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
         1. Calling the parent class setup method
         2. Obtaining SDWAN Manager session data (jsessionid, xsrf_token) using
            cached auth
-        3. Creating and storing an SDWAN Manager client for use in verification methods
+
+        Note: Client creation is deferred to run_async_verification_test() to avoid
+        macOS fork() issues with httpx/SSL. Creating httpx.AsyncClient in a forked
+        process before entering an async context can cause crashes on macOS due to
+        OpenSSL threading primitives that are not fork-safe.
 
         The session data is obtained through the SDWANManagerAuth utility which
         manages session lifecycle and prevents duplicate authentication requests
@@ -86,10 +91,18 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
         super().setup()
 
         # Get shared SDWAN Manager auth data (jsessionid, xsrf_token)
-        self.auth_data = SDWANManagerAuth.get_auth()
+        # This reads from file cache - no httpx client creation here
+        try:
+            self.auth_data = SDWANManagerAuth.get_auth()
+        except (RuntimeError, ValueError) as e:
+            # Convert auth failures to FAILED (not ERRORED) - auth issues are
+            # expected failure conditions, not infrastructure errors
+            self.auth_data = {}  # Ensure attribute exists for cleanup code
+            self.failed(f"Authentication failed: {e}")
+            return
 
-        # Store the SDWAN Manager client for use in verification methods
-        self.client = self.get_sdwan_manager_client()
+        # NOTE: Client creation is deferred to run_async_verification_test()
+        # to avoid macOS fork() + httpx/SSL crash issues
 
     def get_sdwan_manager_client(self) -> httpx.AsyncClient:
         """Get an httpx async client configured for SDWAN Manager.
@@ -141,9 +154,10 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
         Simple entry point that uses base class orchestration to run async
         verification tests. This thin wrapper:
         1. Creates and manages an event loop for async operations
-        2. Calls NACTestBase.run_verification_async() to execute tests
-        3. Passes results to NACTestBase.process_results_smart() for reporting
-        4. Ensures proper cleanup of async resources
+        2. Creates the SDWAN Manager client (deferred from setup for fork safety)
+        3. Calls NACTestBase.run_verification_async() to execute tests
+        4. Passes results to NACTestBase.process_results_smart() for reporting
+        5. Ensures proper cleanup of async resources
 
         The actual verification logic is handled by:
         - get_items_to_verify() - must be implemented by the test class
@@ -158,10 +172,17 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
             This method creates its own event loop to ensure compatibility
             with PyATS synchronous test execution model. The loop and client
             connections are properly closed after test completion.
+
+            Client creation is done HERE (not in setup) to avoid macOS fork()
+            issues with httpx/SSL. Creating httpx.AsyncClient after fork() but
+            before entering an async context can crash on macOS.
         """
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
         try:
+            # Create client INSIDE the event loop context to avoid macOS fork+SSL crash
+            self.client = self.get_sdwan_manager_client()
+
             # Call the base class generic orchestration
             results = loop.run_until_complete(self.run_verification_async())