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

nac_test_pyats_common/__init__.py

@@ -29,7 +29,12 @@ __version__ = "1.0.0"
 
 # Public API - Import from subpackages
 from nac_test_pyats_common.aci import APICAuth, APICTestBase
-from nac_test_pyats_common.catc import CatalystCenterAuth, CatalystCenterTestBase
+from nac_test_pyats_common.catc import (
+    CatalystCenterAuth,
+    CatalystCenterDeviceResolver,
+    CatalystCenterSSHTestBase,
+    CatalystCenterTestBase,
+)
 from nac_test_pyats_common.sdwan import (
     SDWANDeviceResolver,
     SDWANManagerAuth,
@@ -49,4 +54,6 @@ __all__ = [
     # Catalyst Center
     "CatalystCenterAuth",
     "CatalystCenterTestBase",
+    "CatalystCenterSSHTestBase",
+    "CatalystCenterDeviceResolver",
 ]

nac_test_pyats_common/aci/auth.py

@@ -14,17 +14,29 @@ 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 APIC 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 httpx
-from nac_test.pyats_core.common.auth_cache import (
-    AuthCache,  # type: ignore[import-untyped]
+import os
+
+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 APIC authentication tokens in seconds
 # APIC tokens are typically valid for 10 minutes (600 seconds) by default
 APIC_TOKEN_LIFETIME_SECONDS: int = 600
 
+# HTTP timeout for authentication request
+AUTH_REQUEST_TIMEOUT_SECONDS: float = 30.0
+
 
 class APICAuth:
     """APIC-specific authentication implementation with token caching.
@@ -44,19 +56,27 @@ class APICAuth:
     """
 
     @staticmethod
-    def authenticate(url: str, username: str, password: str) -> tuple[str, int]:
+    def authenticate(
+        url: str, username: str, password: str, verify_ssl: bool = False
+    ) -> tuple[str, int]:
         """Perform direct APIC authentication and obtain a session token.
 
         This method performs a direct authentication request to the APIC controller
         using the provided credentials. It returns both the token and its lifetime
         for proper cache management.
 
+        Internally uses execute_auth_subprocess() to run authentication in a clean
+        subprocess, avoiding the macOS fork+SSL crash issue where SSL operations
+        crash after fork().
+
         Args:
             url: Base URL of the APIC controller (e.g., "https://apic.example.com").
                 Should not include trailing slashes or API paths.
             username: APIC username for authentication. This should be a valid user
                 configured in the APIC with appropriate permissions.
             password: Password for the specified APIC user account.
+            verify_ssl: Whether to verify SSL certificates. Defaults to False for
+                backward compatibility with lab environments using self-signed certs.
 
         Returns:
             A tuple containing:
@@ -65,50 +85,100 @@ class APICAuth:
                 - expires_in (int): Token lifetime in seconds (typically 600 seconds).
 
         Raises:
-            httpx.HTTPStatusError: If the APIC returns a non-2xx status code,
-                typically indicating authentication failure (401) or server error.
-            httpx.RequestError: If the request fails due to network issues,
-                connection timeouts, or other transport-level problems.
-            KeyError: If the APIC response doesn't contain the expected JSON
-                structure with token information.
-            ValueError: If the APIC response contains malformed JSON that cannot
-                be parsed.
+            SubprocessAuthError: If authentication subprocess fails or returns an error.
+            ValueError: If the APIC response contains malformed JSON or unexpected
+                structure that cannot be properly parsed.
+
+        Note:
+            SSL verification defaults to disabled to handle self-signed certificates
+            commonly used in lab and development APIC deployments. Set verify_ssl=True
+            for production environments with proper certificate validation.
         """
-        # NOTE: SSL verification is disabled (verify=False) to handle self-signed
-        # certificates commonly used in lab and development APIC deployments.
-        # In production environments, proper certificate validation should be enabled
-        # by either installing the APIC certificate in the trust store or providing
-        # a custom CA bundle via the verify parameter.
-        with httpx.Client(verify=False) as client:
-            response = client.post(
-                f"{url}/api/aaaLogin.json",
-                json={"aaaUser": {"attributes": {"name": username, "pwd": password}}},
-            )
-            response.raise_for_status()
-
-            # Parse the APIC response and extract the token
-            # Response structure:
-            # {"imdata": [{"aaaLogin": {"attributes": {"token": "..."}}}]}
-            try:
-                response_data = response.json()
-                token = response_data["imdata"][0]["aaaLogin"]["attributes"]["token"]
-            except (KeyError, IndexError) as e:
-                # Provide a more informative error message for malformed responses
-                raise ValueError(
-                    f"APIC returned unexpected response structure. "
-                    f"Expected JSON with 'imdata[0].aaaLogin.attributes.token' path. "
-                    f"Actual response: {response.text[:500]}"
-                ) from e
-            except ValueError as e:
-                # Handle JSON parsing errors explicitly
-                raise ValueError(
-                    f"APIC returned invalid JSON response: {response.text[:500]}"
-                ) from e
-
-            return token, APIC_TOKEN_LIFETIME_SECONDS
+        # Build auth parameters for subprocess
+        auth_params = {
+            "url": url,
+            "username": username,
+            "password": password,
+            "timeout": AUTH_REQUEST_TIMEOUT_SECONDS,
+            "verify_ssl": verify_ssl,
+        }
+
+        # APIC-specific authentication logic
+        # This script assumes `params` dict is already loaded by execute_auth_subprocess
+        auth_script_body = """
+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"]
+
+try:
+    # 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
+
+    # Build JSON payload for APIC authentication
+    payload = json.dumps({
+        "aaaUser": {
+            "attributes": {
+                "name": username,
+                "pwd": password
+            }
+        }
+    }).encode("utf-8")
+
+    # Create request with proper headers
+    request = urllib.request.Request(
+        f"{url}/api/aaaLogin.json",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST"
+    )
+
+    # Create HTTPS handler with SSL context
+    https_handler = urllib.request.HTTPSHandler(context=ssl_context)
+    opener = urllib.request.build_opener(https_handler)
+
+    # 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["imdata"][0]["aaaLogin"]["attributes"]["token"]
+    result = {"token": token}
+
+except urllib.error.HTTPError as e:
+    error_body = e.read().decode("utf-8") if e.fp else ""
+    result = {
+        "error": f"HTTP {e.code}: {e.reason}",
+        "response": error_body[:500]
+    }
+except (KeyError, IndexError) as e:
+    result = {
+        "error": f"Unexpected response structure: {str(e)}",
+        "response": response_body[:500] if "response_body" in dir() else ""
+    }
+except Exception as e:
+    result = {"error": str(e)}
+"""
+
+        # Execute authentication in subprocess
+        auth_data = execute_auth_subprocess(auth_params, auth_script_body)
+
+        return auth_data["token"], APIC_TOKEN_LIFETIME_SECONDS
 
     @classmethod
-    def get_token(cls, url: str, username: str, password: str) -> str:
+    def get_token(
+        cls, url: str, username: str, password: str, verify_ssl: bool = False
+    ) -> str:
         """Get APIC token with automatic caching and renewal.
 
         This is the primary method that consumers should use to obtain APIC tokens.
@@ -126,6 +196,8 @@ class APICAuth:
             username: APIC username for authentication. This should be a valid user
                 configured in the APIC with appropriate permissions.
             password: Password for the specified APIC user account.
+            verify_ssl: Whether to verify SSL certificates. Defaults to False for
+                backward compatibility with lab environments using self-signed certs.
 
         Returns:
             A valid APIC session token that can be used in API requests.
@@ -133,13 +205,9 @@ class APICAuth:
             API calls to the APIC controller.
 
         Raises:
-            httpx.HTTPStatusError: If the APIC returns a non-2xx status code during
-                authentication, typically indicating invalid credentials (401) or
-                server issues (5xx).
-            httpx.RequestError: If the request fails due to network issues,
-                connection timeouts, or other transport-level problems.
-            ValueError: If the APIC response contains malformed or unexpected JSON
-                structure that cannot be properly parsed.
+            SubprocessAuthError: If authentication fails due to invalid credentials,
+                network issues, connection timeouts, or APIC server errors. The error
+                message will contain details from the authentication subprocess.
 
         Examples:
             >>> # Get a token for APIC access
@@ -159,5 +227,61 @@ class APICAuth:
             url=url,
             username=username,
             password=password,
-            auth_func=cls.authenticate,
+            auth_func=lambda u, un, pw: cls.authenticate(u, un, pw, verify_ssl),
+        )
+
+    @classmethod
+    def get_auth(cls) -> str:
+        """Get APIC token with automatic caching, using environment variables.
+
+        This is the primary method that consumers should use to obtain APIC tokens
+        when using environment variable configuration. It leverages the AuthCache
+        to efficiently manage token lifecycle.
+
+        Environment Variables Required:
+            APIC_URL: Base URL of the APIC controller
+            APIC_USERNAME: APIC username for authentication
+            APIC_PASSWORD: APIC password for authentication
+            APIC_INSECURE: Optional. Set to "True" to disable SSL verification
+                (default: True for backward compatibility)
+
+        Returns:
+            A valid APIC session token.
+
+        Raises:
+            ValueError: If required environment variables are not set.
+        """
+        url = os.environ.get("APIC_URL")
+        username = os.environ.get("APIC_USERNAME")
+        password = os.environ.get("APIC_PASSWORD")
+        insecure = os.environ.get("APIC_INSECURE", "True").lower() in (
+            "true",
+            "1",
+            "yes",
         )
+
+        # Validate environment variables and collect missing ones
+        missing_vars: list[str] = []
+        if not url:
+            missing_vars.append("APIC_URL")
+        if not username:
+            missing_vars.append("APIC_USERNAME")
+        if not password:
+            missing_vars.append("APIC_PASSWORD")
+
+        if missing_vars:
+            raise ValueError(
+                f"Missing required environment variables: {', '.join(missing_vars)}"
+            )
+
+        # Type narrowing: url, username, password are guaranteed to be str
+        # We raised ValueError above if any were None/empty
+        assert url is not None
+        assert username is not None
+        assert password is not None
+
+        # Normalize URL by removing trailing slash
+        url = url.rstrip("/")
+        verify_ssl = not insecure  # APIC_INSECURE=True means verify=False
+
+        return cls.get_token(url, username, password, verify_ssl)

nac_test_pyats_common/aci/test_base.py

@@ -34,7 +34,8 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
 
     Attributes:
         token (str): APIC authentication token obtained during setup.
-        client (httpx.AsyncClient): Wrapped async HTTP client configured for APIC.
+        client (httpx.AsyncClient | None): Wrapped async HTTP client configured
+            for APIC. Initialized to None, set during run_async_verification_test().
         controller_url (str): Base URL of the APIC controller (inherited).
         username (str): APIC username for authentication (inherited).
         password (str): APIC password for authentication (inherited).
@@ -58,6 +59,8 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
                 self.run_async_verification_test(steps)
     """
 
+    client: httpx.AsyncClient | None = None  # MUST declare at class level
+
     @aetest.setup  # type: ignore[misc, untyped-decorator]
     def setup(self) -> None:
         """Setup method that extends the generic base class setup.
@@ -65,7 +68,11 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         Initializes the APIC test environment by:
         1. Calling the parent class setup method
         2. Obtaining an APIC authentication token using file-based locking
-        3. Creating and storing an APIC 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 authentication token is obtained through the APICAuth utility which
         manages token lifecycle and prevents duplicate authentication requests
@@ -74,12 +81,20 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         super().setup()
 
         # Get shared APIC token using file-based locking
-        self.token = APICAuth.get_token(
-            self.controller_url, self.username, self.password
-        )
-
-        # Store the APIC client for use in verification methods
-        self.client = self.get_apic_client()
+        # This reads from file cache - no httpx client creation here
+        try:
+            self.token = APICAuth.get_token(
+                self.controller_url, self.username, self.password
+            )
+        except (RuntimeError, ValueError) as e:
+            # Convert auth failures to FAILED (not ERRORED) - auth issues are
+            # expected failure conditions, not infrastructure errors
+            self.token = ""  # Ensure attribute exists for cleanup code
+            self.failed(f"Authentication failed: {e}")
+            return
+
+        # NOTE: Client creation is deferred to run_async_verification_test()
+        # to avoid macOS fork() + httpx/SSL crash issues
 
     def get_apic_client(self) -> httpx.AsyncClient:
         """Get an httpx async client configured for APIC with response tracking.
@@ -114,9 +129,10 @@ class APICTestBase(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 APIC 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
@@ -131,10 +147,17 @@ class APICTestBase(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_apic_client()
+
             # Call the base class generic orchestration
             results = loop.run_until_complete(self.run_verification_async())
 
@@ -142,6 +165,6 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
             self.process_results_smart(results, steps)
         finally:
             # Clean up the APIC client connection
-            if hasattr(self, "client"):
+            if self.client is not None:  # MANDATORY: never use hasattr()
                 loop.run_until_complete(self.client.aclose())
             loop.close()

nac_test_pyats_common/catc/__init__.py

@@ -3,15 +3,23 @@
 
 """Catalyst Center adapter module for NAC PyATS testing.
 
-This module provides Catalyst Center-specific authentication and test base class
-implementations for use with the nac-test framework. Catalyst Center (formerly
-DNA Center) is Cisco's enterprise network management platform.
+This module provides Catalyst Center-specific authentication, test base classes, and
+device resolver implementations for use with the nac-test framework. It includes support
+for both Catalyst Center API testing and SSH-based device-to-device (D2D) testing.
 
 Classes:
-    CatalystCenterAuth: Token-based authentication with automatic endpoint detection.
-    CatalystCenterTestBase: Base class for Catalyst Center API tests with tracking.
+    CatalystCenterAuth: Token-based authentication with automatic endpoint
+        detection.
+    CatalystCenterTestBase: Base class for Catalyst Center API tests with
+        tracking.
+    CatalystCenterSSHTestBase: Base class for Catalyst Center SSH/D2D tests
+        with device inventory.
+    CatalystCenterDeviceResolver: Resolves device information from the
+        Catalyst Center data model.
 
 Example:
+    For Catalyst Center API testing:
+
     >>> from nac_test_pyats_common.catc import CatalystCenterTestBase
     >>>
     >>> class VerifyNetworkDevices(CatalystCenterTestBase):
@@ -23,16 +31,26 @@ Example:
     ...             f"/dna/intent/api/v1/network-device/{item}"
     ...         )
     ...         return response.status_code == 200
-    ...
+
+    For SSH/D2D testing:
+
+    >>> from nac_test_pyats_common.catc import CatalystCenterSSHTestBase
+    >>>
+    >>> class VerifyInterfaceStatus(CatalystCenterSSHTestBase):
     ...     @aetest.test
-    ...     def verify_devices(self, steps):
-    ...         self.run_async_verification_test(steps)
+    ...     def verify_interfaces(self, steps, device):
+    ...         # SSH-based verification
+    ...         pass
 """
 
+from .api_test_base import CatalystCenterTestBase
 from .auth import CatalystCenterAuth
-from .test_base import CatalystCenterTestBase
+from .device_resolver import CatalystCenterDeviceResolver
+from .ssh_test_base import CatalystCenterSSHTestBase
 
 __all__ = [
     "CatalystCenterAuth",
     "CatalystCenterTestBase",
+    "CatalystCenterSSHTestBase",
+    "CatalystCenterDeviceResolver",
 ]

nac_test_pyats_common/catc/{test_base.py → api_test_base.py}

@@ -34,15 +34,16 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
     response capture. It serves as the foundation for all Catalyst Center-specific
     API test classes.
 
-    The class follows the same pattern as APICTestBase and VManageTestBase for
+    The class follows the same pattern as APICTestBase and SDWANManagerTestBase for
     consistency across NAC architecture adapters. Token refresh is handled
     automatically by the AuthCache TTL mechanism.
 
     Attributes:
         auth_data (dict): Catalyst Center authentication data containing the
             token obtained during setup.
-        client (httpx.AsyncClient): Wrapped async HTTP client configured for
-            Catalyst Center.
+        client (httpx.AsyncClient | None): Wrapped async HTTP client configured for
+            Catalyst Center. Initialized to None, set during
+            run_async_verification_test().
         controller_url (str): Base URL of the Catalyst Center controller.
         verify_ssl (bool): Whether SSL verification is enabled.
 
@@ -67,6 +68,9 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
                 self.run_async_verification_test(steps)
     """
 
+    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:
         """Setup method that extends the generic base class setup.
@@ -75,7 +79,11 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         1. Calling the parent class setup method
         2. Obtaining Catalyst Center authentication token using cached auth
         3. Configuring SSL verification from environment
-        4. Creating and storing a Catalyst Center 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 authentication token is obtained through the CatalystCenterAuth utility
         which manages token lifecycle and prevents duplicate authentication requests
@@ -84,7 +92,15 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         super().setup()
 
         # Get Catalyst Center auth data (token)
-        self.auth_data = CatalystCenterAuth.get_auth()
+        # This reads from file cache - no httpx client creation here
+        try:
+            self.auth_data = CatalystCenterAuth.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
 
         # Get controller URL from environment
         self.controller_url = os.environ.get("CC_URL", "").rstrip("/")
@@ -93,8 +109,8 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         insecure = os.environ.get("CC_INSECURE", "True").lower() in ("true", "1", "yes")
         self.verify_ssl = not insecure
 
-        # Store the Catalyst Center client for use in verification methods
-        self.client = self.get_catc_client()
+        # NOTE: Client creation is deferred to run_async_verification_test()
+        # to avoid macOS fork() + httpx/SSL crash issues
 
     def get_catc_client(self) -> httpx.AsyncClient:
         """Get an httpx async client configured for Catalyst Center.
@@ -144,9 +160,10 @@ class CatalystCenterTestBase(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 Catalyst Center 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
@@ -161,10 +178,17 @@ class CatalystCenterTestBase(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_catc_client()
+
             # Call the base class generic orchestration
             results = loop.run_until_complete(self.run_verification_async())
 
@@ -172,6 +196,6 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
             self.process_results_smart(results, steps)
         finally:
             # Clean up the Catalyst Center client connection
-            if hasattr(self, "client"):
+            if self.client is not None:  # MANDATORY: never use hasattr()
                 loop.run_until_complete(self.client.aclose())
             loop.close()