nac-test-pyats-common 0.1.1__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

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""Catalyst Center-specific device resolver for parsing the NAC data model.
+
+This module provides the CatalystCenterDeviceResolver class, which extends
+BaseDeviceResolver to implement Catalyst Center schema navigation for D2D testing.
+"""
+
+import logging
+from typing import Any
+
+from nac_test_pyats_common.common import BaseDeviceResolver
+from nac_test_pyats_common.iosxe.registry import register_iosxe_resolver
+
+logger = logging.getLogger(__name__)
+
+
+@register_iosxe_resolver("CC")
+class CatalystCenterDeviceResolver(BaseDeviceResolver):
+    """Catalyst Center device resolver for D2D testing.
+
+    Navigates the Catalyst Center NAC schema (catalyst_center.inventory.devices[])
+    to extract device information for SSH testing.
+
+    Schema structure:
+        catalyst_center:
+          inventory:
+            devices:
+              - name: P3-BN1
+                fqdn_name: P3-BN1.cisco.eu
+                device_ip: 192.168.38.1
+                pid: C9300-24P
+                state: PROVISION
+                device_role: ACCESS
+                site: Global/MAX_AREA/MAX_BUILDING
+
+    Credentials:
+        Uses IOSXE_USERNAME and IOSXE_PASSWORD environment variables
+        for SSH access to managed IOS-XE devices.
+
+    Example:
+        >>> resolver = CatalystCenterDeviceResolver(data_model)
+        >>> devices = resolver.get_resolved_inventory()
+        >>> for device in devices:
+        ...     print(f"{device['hostname']}: {device['host']}")
+    """
+
+    def get_architecture_name(self) -> str:
+        """Return 'catalyst_center' as the architecture identifier.
+
+        Returns:
+            Architecture name used in logging and error messages.
+        """
+        return "catalyst_center"
+
+    def get_schema_root_key(self) -> str:
+        """Return 'catalyst_center' as the root key in the data model.
+
+        Returns:
+            Root key used when navigating the schema.
+        """
+        return "catalyst_center"
+
+    def navigate_to_devices(self) -> list[dict[str, Any]]:
+        """Navigate Catalyst Center schema: catalyst_center.inventory.devices[].
+
+        Traverses the Catalyst Center data model structure to find all
+        managed devices in the inventory.
+
+        Returns:
+            List of device dictionaries from the inventory.
+        """
+        devices: list[dict[str, Any]] = []
+        cc_data = self.data_model.get("catalyst_center", {})
+        inventory = cc_data.get("inventory", {})
+        devices.extend(inventory.get("devices", []))
+        return devices
+
+    def validate_device_data(self, device_data: dict[str, Any]) -> None:
+        """Validate device state before extraction.
+
+        Skip devices with INIT or PNP states as they are not fully provisioned.
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Raises:
+            ValueError: If the device has an unsupported state (INIT, PNP).
+        """
+        state = device_data.get("state", "").upper()
+        if state in ("INIT", "PNP"):
+            raise ValueError(
+                f"Device has unsupported state '{state}' "
+                "(devices in INIT or PNP state are not fully provisioned)"
+            )
+
+    def extract_hostname(self, device_data: dict[str, Any]) -> str:
+        """Extract hostname from the 'name' field.
+
+        Uses the device name as the hostname for SSH connections.
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Returns:
+            Device hostname string.
+        """
+        name = device_data.get("name")
+        if not name:
+            raise ValueError("Device missing 'name' field")
+        return str(name)
+
+    def extract_host_ip(self, device_data: dict[str, Any]) -> str:
+        """Extract management IP from device_ip field.
+
+        Reads the device_ip field directly from the device data.
+        Handles CIDR notation if present (e.g., "10.1.1.100/32" -> "10.1.1.100").
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Returns:
+            IP address string without CIDR notation (e.g., "192.168.38.1").
+
+        Raises:
+            ValueError: If device_ip field is not found.
+        """
+        device_ip = device_data.get("device_ip")
+        if not device_ip:
+            raise ValueError(
+                "Device missing 'device_ip' field. "
+                "Ensure device_ip is configured in the inventory."
+            )
+
+        ip_value = str(device_ip)
+
+        # Strip CIDR notation if present
+        if "/" in ip_value:
+            ip_value = ip_value.split("/")[0]
+
+        return ip_value
+
+    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 from the data model.
+
+        Returns:
+            Dictionary with 'os' key (and potentially platform/model in future).
+        """
+        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.
+
+        Catalyst Center D2D tests connect to IOS-XE devices,
+        NOT the Catalyst Center controller.
+
+        Returns:
+            Tuple of (username_env_var, password_env_var).
+        """
+        return ("IOSXE_USERNAME", "IOSXE_PASSWORD")

nac_test_pyats_common/catc/ssh_test_base.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""Catalyst Center specific base test class for SSH/Direct-to-Device testing.
+
+This module provides the CatalystCenterSSHTestBase class, which extends the generic
+SSHTestBase to add Catalyst Center-specific functionality for device-to-device (D2D)
+testing.
+
+The class delegates device inventory resolution to CatalystCenterDeviceResolver, which
+handles all Catalyst Center schema navigation and credential injection.
+
+Credentials:
+    Catalyst Center D2D tests connect to IOS-XE devices managed by Catalyst Center,
+    NOT the Catalyst Center controller. Set these environment variables:
+    - IOSXE_USERNAME: SSH username for managed devices
+    - IOSXE_PASSWORD: SSH password for managed devices
+"""
+
+import logging
+import os
+from typing import Any
+
+from nac_test.pyats_core.common.ssh_base_test import (
+    SSHTestBase,  # type: ignore[import-untyped]
+)
+
+from .device_resolver import CatalystCenterDeviceResolver
+
+logger = logging.getLogger(__name__)
+
+
+class CatalystCenterSSHTestBase(SSHTestBase):  # type: ignore[misc]
+    """Catalyst Center-specific base test class for SSH/D2D testing.
+
+    This class extends SSHTestBase and implements the contract required by
+    nac-test's SSH execution engine. Device inventory resolution is fully
+    delegated to CatalystCenterDeviceResolver.
+
+    Credentials:
+        Catalyst Center D2D tests require IOSXE_USERNAME and IOSXE_PASSWORD
+        environment variables (NOT CC_* which are for the controller).
+
+    Example:
+        class MyCatalystCenterSSHTest(CatalystCenterSSHTestBase):
+            @aetest.test
+            def verify_device_connectivity(self, steps, device):
+                # SSH-based verification logic here
+                pass
+    """
+
+    # Class-level storage for the last resolver instance
+    # This allows nac-test to access skipped_devices after calling
+    # get_ssh_device_inventory()
+    _last_resolver: "CatalystCenterDeviceResolver | None" = None
+
+    @classmethod
+    def get_ssh_device_inventory(
+        cls, data_model: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        """Parse the Catalyst Center data model to retrieve the device inventory.
+
+        This method is the entry point called by nac-test's orchestrator.
+        All device inventory resolution is delegated to CatalystCenterDeviceResolver,
+        which handles:
+        - Schema navigation (catalyst_center.inventory.devices[])
+        - Device metadata extraction (name, device_ip, etc.)
+        - Credential injection (IOSXE_USERNAME, IOSXE_PASSWORD)
+
+        After calling this method, access cls._last_resolver.skipped_devices
+        to get information about devices that failed resolution.
+
+        Args:
+            data_model: The merged data model from nac-test containing all
+                configuration data with resolved variables.
+
+        Returns:
+            List of device dictionaries, each containing:
+            - hostname (str): Device hostname
+            - host (str): Management IP address for SSH connection
+            - os (str): Operating system type (e.g., "iosxe")
+            - username (str): SSH username from IOSXE_USERNAME
+            - password (str): SSH password from IOSXE_PASSWORD
+            - device_id (str): Device identifier (name)
+
+        Raises:
+            ValueError: If IOSXE_USERNAME or IOSXE_PASSWORD env vars are not set.
+        """
+        logger.info(
+            "CatalystCenterSSHTestBase: Resolving device inventory via "
+            "CatalystCenterDeviceResolver"
+        )
+
+        cls._last_resolver = CatalystCenterDeviceResolver(data_model)
+        return cls._last_resolver.get_resolved_inventory()
+
+    def get_device_credentials(self, device: dict[str, Any]) -> dict[str, str | None]:
+        """Get Catalyst Center managed device SSH credentials from env vars.
+
+        Catalyst Center D2D tests connect to IOS-XE devices managed by
+        Catalyst Center, NOT the Catalyst Center controller. Use IOSXE_*
+        environment variables.
+
+        Args:
+            device: Device dictionary (not used - all devices share credentials).
+
+        Returns:
+            Dictionary containing:
+            - username (str | None): SSH username from IOSXE_USERNAME
+            - password (str | None): SSH password from IOSXE_PASSWORD
+        """
+        return {
+            "username": os.environ.get("IOSXE_USERNAME"),
+            "password": os.environ.get("IOSXE_PASSWORD"),
+        }