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

nac_test_pyats_common/__init__.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """NAC PyATS Common - Architecture adapters for NAC PyATS testing.
 
 This package provides architecture-specific authentication, test base classes,
@@ -26,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,
@@ -46,4 +54,6 @@ __all__ = [
     # Catalyst Center
     "CatalystCenterAuth",
     "CatalystCenterTestBase",
+    "CatalystCenterSSHTestBase",
+    "CatalystCenterDeviceResolver",
 ]

nac_test_pyats_common/aci/__init__.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """ACI adapter module for PyATS common utilities.
 
 This module provides the core ACI-specific components for PyATS testing, including

nac_test_pyats_common/aci/auth.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """APIC authentication module for Cisco ACI (Application Centric Infrastructure).
 
 This module provides authentication functionality for Cisco APIC (Application Policy
@@ -14,7 +17,9 @@ re-authenticating when necessary, reducing unnecessary API calls to the APIC con
 """
 
 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,  # 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
@@ -82,7 +87,8 @@ class APICAuth:
             response.raise_for_status()
 
             # Parse the APIC response and extract the token
-            # Response structure: {"imdata": [{"aaaLogin": {"attributes": {"token": "..."}}}]}
+            # Response structure:
+            # {"imdata": [{"aaaLogin": {"attributes": {"token": "..."}}}]}
             try:
                 response_data = response.json()
                 token = response_data["imdata"][0]["aaaLogin"]["attributes"]["token"]

nac_test_pyats_common/aci/test_base.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """APIC-specific base test class for ACI API testing.
 
 This module provides the APICTestBase class, which extends the generic NACTestBase
@@ -13,7 +16,9 @@ import asyncio
 from typing import Any
 
 import httpx
-from nac_test.pyats_core.common.base_test import NACTestBase  # type: ignore[import-untyped]
+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
@@ -69,7 +74,9 @@ 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)
+        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()
@@ -94,7 +101,9 @@ class APICTestBase(NACTestBase):  # type: ignore[misc]
         """
         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)
+        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]

nac_test_pyats_common/catc/__init__.py

@@ -1,14 +1,25 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """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):
@@ -20,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}

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """Catalyst Center-specific base test class for API testing.
 
 This module provides the CatalystCenterTestBase class, which extends the generic
@@ -14,7 +17,9 @@ import os
 from typing import Any
 
 import httpx
-from nac_test.pyats_core.common.base_test import NACTestBase  # type: ignore[import-untyped]
+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 CatalystCenterAuth
@@ -52,7 +57,9 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
                 return ['device1', 'device2']
 
             async def verify_item(self, item):
-                response = await self.client.get(f"/dna/intent/api/v1/network-device/{item}")
+                response = await self.client.get(
+                    f"/dna/intent/api/v1/network-device/{item}"
+                )
                 return response.status_code == 200
 
             @aetest.test
@@ -90,7 +97,9 @@ class CatalystCenterTestBase(NACTestBase):  # type: ignore[misc]
         self.client = self.get_catc_client()
 
     def get_catc_client(self) -> httpx.AsyncClient:
-        """Get an httpx async client configured for Catalyst Center with response tracking.
+        """Get an httpx async client configured for Catalyst Center.
+
+        Configured with response tracking.
 
         Creates an HTTP client specifically configured for Catalyst Center API
         communication with authentication headers, base URL, and automatic response

nac_test_pyats_common/catc/auth.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """Catalyst Center-specific authentication implementation.
 
 This module provides authentication functionality for Cisco Catalyst Center
@@ -5,7 +8,8 @@ This module provides authentication functionality for Cisco Catalyst Center
 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
+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
@@ -16,7 +20,9 @@ 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,  # 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
@@ -96,7 +102,9 @@ class CatalystCenterAuth:
         """
         last_error: Exception | None = None
 
-        with httpx.Client(verify=verify_ssl, timeout=AUTH_REQUEST_TIMEOUT_SECONDS) as client:
+        with httpx.Client(
+            verify=verify_ssl, timeout=AUTH_REQUEST_TIMEOUT_SECONDS
+        ) as client:
             for endpoint in AUTH_ENDPOINTS:
                 try:
                     auth_response = client.post(
@@ -129,7 +137,8 @@ class CatalystCenterAuth:
 
             # All endpoints failed
             raise RuntimeError(
-                f"Catalyst Center authentication failed on all endpoints. Last error: {last_error}"
+                f"Catalyst Center authentication failed on all endpoints. "
+                f"Last error: {last_error}"
             ) from last_error
 
     @classmethod
@@ -148,7 +157,8 @@ class CatalystCenterAuth:
             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)
+            CC_INSECURE: Optional. Set to "True" to disable SSL verification
+                (default: True)
 
         Returns:
             A dictionary containing:
@@ -186,7 +196,9 @@ class CatalystCenterAuth:
                 missing_vars.append("CC_USERNAME")
             if not password:
                 missing_vars.append("CC_PASSWORD")
-            raise ValueError(f"Missing required environment variables: {', '.join(missing_vars)}")
+            raise ValueError(
+                f"Missing required environment variables: {', '.join(missing_vars)}"
+            )
 
         # Normalize URL by removing trailing slash
         url = url.rstrip("/")  # type: ignore[union-attr]

nac_test_pyats_common/catc/device_resolver.py

@@ -0,0 +1,164 @@
+# 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_type(self, device_data: dict[str, Any]) -> str:
+        """Return 'iosxe' as all managed devices are IOS-XE based.
+
+        Args:
+            device_data: Device data dictionary (unused, OS is hardcoded).
+
+        Returns:
+            Always returns 'iosxe'.
+        """
+        return "iosxe"
+
+    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"),
+        }

nac_test_pyats_common/common/__init__.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """Common base classes for nac-test-pyats-common.
 
 This module provides architecture-agnostic base classes that can be extended