nac-test-pyats-common 0.1.0__py3-none-any.whl

nac_test_pyats_common/__init__.py

@@ -0,0 +1,49 @@
+"""NAC PyATS Common - Architecture adapters for NAC PyATS testing.
+
+This package provides architecture-specific authentication, test base classes,
+and device resolver implementations for use with the nac-test framework. It
+consolidates duplicated PyATS testing infrastructure from multiple NAC
+architecture repositories (ACI, SD-WAN, Catalyst Center) into a single,
+centralized, and maintainable package.
+
+Supported Architectures:
+    - ACI (APIC): nac_test_pyats_common.aci
+    - SD-WAN (SDWAN Manager): nac_test_pyats_common.sdwan
+    - Catalyst Center: nac_test_pyats_common.catc
+
+Example:
+    >>> # For ACI/APIC testing
+    >>> from nac_test_pyats_common.aci import APICTestBase
+    >>>
+    >>> # For SD-WAN/SDWAN Manager testing
+    >>> from nac_test_pyats_common.sdwan import SDWANManagerTestBase, SDWANTestBase
+    >>>
+    >>> # For Catalyst Center testing
+    >>> from nac_test_pyats_common.catc import CatalystCenterTestBase
+"""
+
+__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.sdwan import (
+    SDWANDeviceResolver,
+    SDWANManagerAuth,
+    SDWANManagerTestBase,
+    SDWANTestBase,
+)
+
+__all__ = [
+    # ACI/APIC
+    "APICAuth",
+    "APICTestBase",
+    # SD-WAN/SDWAN Manager
+    "SDWANManagerAuth",
+    "SDWANManagerTestBase",
+    "SDWANTestBase",
+    "SDWANDeviceResolver",
+    # Catalyst Center
+    "CatalystCenterAuth",
+    "CatalystCenterTestBase",
+]

nac_test_pyats_common/aci/__init__.py

@@ -0,0 +1,40 @@
+"""ACI adapter module for PyATS common utilities.
+
+This module provides the core ACI-specific components for PyATS testing, including
+authentication handling and base test classes. It serves as the primary interface
+for interacting with Cisco ACI (Application Centric Infrastructure) environments
+within the PyATS testing framework.
+
+The module exports two primary components:
+1. APICAuth: Handles authentication and session management for APIC controllers
+2. APICTestBase: Provides the base class for all ACI-specific PyATS tests
+
+Example:
+    Basic usage of the ACI module components:
+
+    ```python
+    from nac_test_pyats_common.aci import APICAuth, APICTestBase
+
+    # Create authentication handler
+    auth = APICAuth(
+        controller_url="https://apic.example.com",
+        username="admin",
+        password="password123"
+    )
+
+    # Use in a test class
+    class MyACITest(APICTestBase):
+        def setup(self):
+            self.auth = auth
+            super().setup()
+    ```
+
+Note:
+    This module is specifically designed for testing ACI environments and requires
+    proper APIC controller access and credentials for full functionality.
+"""
+
+from .auth import APICAuth
+from .test_base import APICTestBase
+
+__all__ = ["APICAuth", "APICTestBase"]

nac_test_pyats_common/aci/auth.py

@@ -0,0 +1,157 @@
+"""APIC authentication module for Cisco ACI (Application Centric Infrastructure).
+
+This module provides authentication functionality for Cisco APIC (Application Policy
+Infrastructure Controller), which is the central management and policy enforcement
+point for ACI fabric. The authentication mechanism uses REST API calls to obtain
+session tokens that are valid for a limited time period.
+
+The module implements a two-tier API design:
+1. authenticate() - Low-level method that performs direct APIC authentication
+2. get_token() - High-level method that leverages caching for efficient token reuse
+
+This design ensures efficient token management by reusing valid tokens and only
+re-authenticating when necessary, reducing unnecessary API calls to the APIC controller.
+"""
+
+import httpx
+from nac_test.pyats_core.common.auth_cache import AuthCache  # type: ignore[import-untyped]
+
+# 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
+
+
+class APICAuth:
+    """APIC-specific authentication implementation with token caching.
+
+    This class provides a two-tier API for APIC authentication:
+
+    1. Low-level authenticate() method: Directly authenticates with APIC and returns
+       a token along with its expiration time. This is typically used by the caching
+       layer and not called directly by consumers.
+
+    2. High-level get_token() method: Provides cached token management, automatically
+       handling token renewal when expired. This is the primary method that consumers
+       should use for obtaining APIC tokens.
+
+    The two-tier design ensures efficient token reuse across multiple API calls while
+    maintaining clean separation between authentication logic and caching concerns.
+    """
+
+    @staticmethod
+    def authenticate(url: str, username: str, password: str) -> 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.
+
+        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.
+
+        Returns:
+            A tuple containing:
+                - token (str): The APIC session token that should be included in
+                  subsequent API requests as a cookie (APIC-cookie).
+                - 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.
+        """
+        # 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
+
+    @classmethod
+    def get_token(cls, url: str, username: str, password: str) -> str:
+        """Get APIC token with automatic caching and renewal.
+
+        This is the primary method that consumers should use to obtain APIC tokens.
+        It leverages the AuthCache to efficiently manage token lifecycle, reusing
+        valid tokens and automatically renewing expired ones. This significantly
+        reduces the number of authentication requests to the APIC controller.
+
+        The method uses a cache key based on the controller type ("ACI"), URL,
+        and username to ensure proper token isolation between different APIC
+        instances and user accounts.
+
+        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.
+
+        Returns:
+            A valid APIC session token that can be used in API requests.
+            The token should be included as a cookie (APIC-cookie) in subsequent
+            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.
+
+        Examples:
+            >>> # Get a token for APIC access
+            >>> token = APICAuth.get_token(
+            ...     url="https://apic.example.com",
+            ...     username="admin",
+            ...     password="password123"
+            ... )
+            >>> # Use the token in subsequent API calls
+            >>> headers = {"Cookie": f"APIC-cookie={token}"}
+        """
+        # AuthCache.get_or_create_token returns str, but mypy can't verify this
+        # because nac_test lacks py.typed marker. The return type is guaranteed
+        # by AuthCache's implementation which uses extract_token=True mode.
+        return AuthCache.get_or_create_token(  # type: ignore[no-any-return]
+            controller_type="ACI",
+            url=url,
+            username=username,
+            password=password,
+            auth_func=cls.authenticate,
+        )

nac_test_pyats_common/aci/test_base.py

@@ -0,0 +1,138 @@
+"""APIC-specific base test class for ACI API testing.
+
+This module provides the APICTestBase class, which extends the generic NACTestBase
+to add ACI-specific functionality for testing APIC controllers. It handles
+authentication, client management, and provides a standardized interface for
+running asynchronous verification tests against ACI fabrics.
+
+The class integrates with PyATS/Genie test frameworks and provides automatic
+API call tracking for enhanced HTML reporting.
+"""
+
+import asyncio
+from typing import Any
+
+import httpx
+from nac_test.pyats_core.common.base_test import NACTestBase  # type: ignore[import-untyped]
+from pyats import aetest  # type: ignore[import-untyped]
+
+from .auth import APICAuth
+
+
+class APICTestBase(NACTestBase):  # type: ignore[misc]
+    """Base class for APIC API tests with enhanced reporting.
+
+    This class extends the generic NACTestBase to provide APIC-specific
+    functionality including APIC authentication token management, API call
+    tracking for HTML reports, and wrapped HTTP client for automatic response
+    capture. It serves as the foundation for all ACI-specific test classes.
+
+    Attributes:
+        token (str): APIC authentication token obtained during setup.
+        client (httpx.AsyncClient): Wrapped async HTTP client configured for APIC.
+        controller_url (str): Base URL of the APIC controller (inherited).
+        username (str): APIC username for authentication (inherited).
+        password (str): APIC password for authentication (inherited).
+
+    Methods:
+        setup(): Initialize APIC authentication and client.
+        get_apic_client(): Create and configure an APIC-specific HTTP client.
+        run_async_verification_test(): Execute async verification tests with PyATS.
+
+    Example:
+        class MyAPICTest(APICTestBase):
+            async def get_items_to_verify(self):
+                return ['tenant1', 'tenant2']
+
+            async def verify_item(self, item):
+                # Custom verification logic here
+                pass
+
+            @aetest.test
+            def verify_tenants(self, steps):
+                self.run_async_verification_test(steps)
+    """
+
+    @aetest.setup  # type: ignore[misc, untyped-decorator]
+    def setup(self) -> None:
+        """Setup method that extends the generic base class setup.
+
+        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
+
+        The authentication token is obtained through the APICAuth utility which
+        manages token lifecycle and prevents duplicate authentication requests
+        across parallel test execution.
+        """
+        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()
+
+    def get_apic_client(self) -> httpx.AsyncClient:
+        """Get an httpx async client configured for APIC with response tracking.
+
+        Creates an HTTP client specifically configured for APIC API communication
+        with authentication headers, base URL, and automatic response tracking
+        for HTML report generation. The client is wrapped to capture all API
+        interactions for detailed test reporting.
+
+        Returns:
+            httpx.AsyncClient: Configured client with APIC authentication, base URL,
+                and wrapped for automatic API call tracking. The client has SSL
+                verification disabled for lab environment compatibility.
+
+        Note:
+            SSL verification is disabled (verify=False) to support lab environments
+            with self-signed certificates. For production environments, consider
+            enabling SSL verification with proper certificate management.
+        """
+        headers = {"Cookie": f"APIC-cookie={self.token}"}
+        # SSL verification disabled for lab environment compatibility
+        client = self.pool.get_client(base_url=self.controller_url, headers=headers, verify=False)
+
+        # Use the generic tracking wrapper from base class
+        return self.wrap_client_for_tracking(client, device_name="APIC")  # type: ignore[no-any-return]
+
+    def run_async_verification_test(self, steps: Any) -> None:
+        """Execute asynchronous verification tests with PyATS step tracking.
+
+        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
+
+        The actual verification logic is handled by:
+        - get_items_to_verify() - must be implemented by the test class
+        - verify_item() - must be implemented by the test class
+
+        Args:
+            steps: PyATS steps object for test reporting and step management.
+                Each verification item will be executed as a separate step
+                with automatic pass/fail tracking.
+
+        Note:
+            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.
+        """
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            # Call the base class generic orchestration
+            results = loop.run_until_complete(self.run_verification_async())
+
+            # Process results using smart configuration-driven processing
+            self.process_results_smart(results, steps)
+        finally:
+            # Clean up the APIC client connection
+            if hasattr(self, "client"):
+                loop.run_until_complete(self.client.aclose())
+            loop.close()

nac_test_pyats_common/catc/__init__.py

@@ -0,0 +1,35 @@
+"""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.
+
+Classes:
+    CatalystCenterAuth: Token-based authentication with automatic endpoint detection.
+    CatalystCenterTestBase: Base class for Catalyst Center API tests with tracking.
+
+Example:
+    >>> from nac_test_pyats_common.catc import CatalystCenterTestBase
+    >>>
+    >>> class VerifyNetworkDevices(CatalystCenterTestBase):
+    ...     async def get_items_to_verify(self):
+    ...         return ['device-uuid-1', 'device-uuid-2']
+    ...
+    ...     async def verify_item(self, item):
+    ...         response = await self.client.get(
+    ...             f"/dna/intent/api/v1/network-device/{item}"
+    ...         )
+    ...         return response.status_code == 200
+    ...
+    ...     @aetest.test
+    ...     def verify_devices(self, steps):
+    ...         self.run_async_verification_test(steps)
+"""
+
+from .auth import CatalystCenterAuth
+from .test_base import CatalystCenterTestBase
+
+__all__ = [
+    "CatalystCenterAuth",
+    "CatalystCenterTestBase",
+]

nac_test_pyats_common/catc/auth.py

@@ -0,0 +1,205 @@
+"""Catalyst Center-specific authentication implementation.
+
+This module provides authentication functionality for Cisco Catalyst Center
+(formerly DNA Center), which is the central management platform for enterprise
+networks. The authentication mechanism uses token-based login with Basic Auth.
+
+The module implements a two-tier API design:
+1. _authenticate() - Low-level method that performs direct Catalyst Center authentication
+2. get_auth() - High-level method that leverages caching for efficient token reuse
+
+This design ensures efficient token management by reusing valid tokens and only
+re-authenticating when necessary, reducing unnecessary API calls to the controller.
+"""
+
+import os
+from typing import Any
+
+import httpx
+from nac_test.pyats_core.common.auth_cache import AuthCache  # type: ignore[import-untyped]
+
+# Default token lifetime for Catalyst Center authentication in seconds
+# Catalyst Center tokens are typically valid for 1 hour (3600 seconds) by default
+CATALYST_CENTER_TOKEN_LIFETIME_SECONDS: int = 3600
+
+# HTTP timeout for authentication request
+AUTH_REQUEST_TIMEOUT_SECONDS: float = 30.0
+
+# Auth endpoints (try modern first, fallback to legacy)
+AUTH_ENDPOINTS: list[str] = [
+    "/api/system/v1/auth/token",  # Modern (Catalyst Center 2.x)
+    "/dna/system/api/v1/auth/token",  # Legacy (DNA Center 1.x/2.x)
+]
+
+
+class CatalystCenterAuth:
+    """Catalyst Center-specific authentication implementation with token caching.
+
+    This class provides a two-tier API for Catalyst Center authentication:
+
+    1. Low-level _authenticate() method: Directly authenticates with Catalyst Center
+       using Basic Auth and returns token data along with expiration time. This is
+       typically used by the caching layer and not called directly by consumers.
+
+    2. High-level get_auth() method: Provides cached token management, automatically
+       handling token renewal when expired. This is the primary method that consumers
+       should use for obtaining Catalyst Center tokens.
+
+    The authentication flow supports both:
+    - Modern Catalyst Center 2.x: /api/system/v1/auth/token endpoint
+    - Legacy DNA Center 1.x/2.x: /dna/system/api/v1/auth/token endpoint
+
+    The class mirrors VManageAuth pattern for consistency across NAC adapters.
+
+    Example:
+        >>> # Get authentication data for Catalyst Center API calls
+        >>> auth_data = CatalystCenterAuth.get_auth()
+        >>> # Use in requests
+        >>> headers = {"X-Auth-Token": auth_data["token"]}
+    """
+
+    @classmethod
+    def _authenticate(
+        cls, url: str, username: str, password: str, verify_ssl: bool
+    ) -> tuple[dict[str, Any], int]:
+        """Perform direct Catalyst Center authentication and obtain token.
+
+        This method performs a direct authentication request to the Catalyst Center
+        using Basic Auth. It tries the modern auth endpoint first, then falls back
+        to the legacy endpoint if needed for backward compatibility.
+
+        Args:
+            url: Base URL of the Catalyst Center (e.g., "https://catc.example.com").
+                Should not include trailing slashes or API paths.
+            username: Catalyst Center username for authentication. This should be
+                a valid user configured with appropriate permissions.
+            password: Password for the specified Catalyst Center user account.
+            verify_ssl: Whether to verify SSL certificates. Set to False for
+                lab environments with self-signed certificates.
+
+        Returns:
+            A tuple containing:
+                - auth_dict (dict): Dictionary with 'token' (str) containing the
+                  authentication token for API requests.
+                - 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.
+
+        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. Last error: {last_error}"
+            ) from last_error
+
+    @classmethod
+    def get_auth(cls) -> dict[str, Any]:
+        """Get Catalyst Center authentication data with automatic caching and renewal.
+
+        This is the primary method that consumers should use to obtain Catalyst Center
+        tokens. It leverages the AuthCache to efficiently manage token lifecycle,
+        reusing valid tokens and automatically renewing expired ones. This significantly
+        reduces the number of authentication requests to the Catalyst Center.
+
+        The method uses a cache key based on the controller type ("CC") and URL
+        to ensure proper token isolation between different Catalyst Center instances.
+
+        Environment Variables Required:
+            CC_URL: Base URL of the Catalyst Center
+            CC_USERNAME: Catalyst Center username for authentication
+            CC_PASSWORD: Catalyst Center password for authentication
+            CC_INSECURE: Optional. Set to "True" to disable SSL verification (default: True)
+
+        Returns:
+            A dictionary containing:
+                - token (str): The authentication token for API requests.
+                  Should be included as X-Auth-Token header in subsequent calls.
+
+        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.
+
+        Example:
+            >>> # Set environment variables first
+            >>> import os
+            >>> os.environ["CC_URL"] = "https://catalyst.example.com"
+            >>> os.environ["CC_USERNAME"] = "admin"
+            >>> os.environ["CC_PASSWORD"] = "password123"
+            >>> os.environ["CC_INSECURE"] = "True"  # For lab environments
+            >>> # Get authentication data
+            >>> auth_data = CatalystCenterAuth.get_auth()
+            >>> # Use in API requests
+            >>> headers = {"X-Auth-Token": auth_data["token"]}
+        """
+        url = os.environ.get("CC_URL")
+        username = os.environ.get("CC_USERNAME")
+        password = os.environ.get("CC_PASSWORD")
+        insecure = os.environ.get("CC_INSECURE", "True").lower() in ("true", "1", "yes")
+
+        if not all([url, username, password]):
+            missing_vars: list[str] = []
+            if not url:
+                missing_vars.append("CC_URL")
+            if not username:
+                missing_vars.append("CC_USERNAME")
+            if not password:
+                missing_vars.append("CC_PASSWORD")
+            raise ValueError(f"Missing required environment variables: {', '.join(missing_vars)}")
+
+        # Normalize URL by removing trailing slash
+        url = url.rstrip("/")  # type: ignore[union-attr]
+        verify_ssl = not insecure  # CC_INSECURE=True means verify=False
+
+        def auth_wrapper() -> tuple[dict[str, Any], int]:
+            """Wrapper for authentication that captures closure variables."""
+            return cls._authenticate(url, username, password, verify_ssl)  # type: ignore[arg-type]
+
+        # AuthCache.get_or_create returns dict[str, Any], but mypy can't verify this
+        # because nac_test lacks py.typed marker.
+        return AuthCache.get_or_create(  # type: ignore[no-any-return]
+            controller_type="CC",
+            url=url,
+            auth_func=auth_wrapper,
+        )