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

nac_test_pyats_common/sdwan/auth.py

@@ -0,0 +1,215 @@
+"""SDWAN Manager authentication implementation for Cisco SD-WAN.
+
+This module provides authentication functionality for Cisco SDWAN Manager (formerly
+vManage), which manages the software-defined WAN fabric. The authentication mechanism
+uses form-based login with JSESSIONID cookie and optional XSRF token for CSRF protection.
+
+The module implements a two-tier API design:
+1. _authenticate() - Low-level method that performs direct SDWAN Manager authentication
+2. get_auth() - High-level method that leverages caching for efficient token reuse
+
+This design ensures efficient session management by reusing valid sessions and only
+re-authenticating when necessary, reducing unnecessary API calls to the SDWAN Manager.
+"""
+
+import os
+from typing import Any
+
+import httpx
+from nac_test.pyats_core.common.auth_cache import AuthCache  # type: ignore[import-untyped]
+
+# Default session lifetime for SDWAN Manager authentication in seconds
+# SDWAN Manager sessions are typically valid for 30 minutes (1800 seconds) by default
+SDWAN_MANAGER_SESSION_LIFETIME_SECONDS: int = 1800
+
+# HTTP timeout for XSRF token fetch (shorter than auth timeout since it's optional)
+XSRF_TOKEN_FETCH_TIMEOUT_SECONDS: float = 10.0
+
+# HTTP timeout for authentication request
+AUTH_REQUEST_TIMEOUT_SECONDS: float = 30.0
+
+
+class SDWANManagerAuth:
+    """SDWAN Manager authentication implementation with session caching.
+
+    This class provides a two-tier API for SDWAN Manager authentication:
+
+    1. Low-level _authenticate() method: Directly authenticates with SDWAN Manager using
+       form-based login and returns session 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 session management, automatically
+       handling session renewal when expired. This is the primary method that consumers
+       should use for obtaining SDWAN Manager authentication data.
+
+    The authentication flow supports both:
+    - Pre-19.2 versions: JSESSIONID cookie only
+    - 19.2+ versions: JSESSIONID cookie plus X-XSRF-TOKEN header for CSRF protection
+
+    Example:
+        >>> # Get authentication data for SDWAN Manager API calls
+        >>> auth_data = SDWANManagerAuth.get_auth()
+        >>> # Use in requests
+        >>> headers = {"Cookie": f"JSESSIONID={auth_data['jsessionid']}"}
+        >>> if auth_data.get("xsrf_token"):
+        ...     headers["X-XSRF-TOKEN"] = auth_data["xsrf_token"]
+    """
+
+    @staticmethod
+    def _authenticate(url: str, username: str, password: str) -> tuple[dict[str, Any], int]:
+        """Perform direct SDWAN Manager authentication and obtain session data.
+
+        This method performs a direct authentication request to the SDWAN Manager
+        using form-based login. It returns both the session data and its lifetime
+        for proper cache management.
+
+        The authentication process:
+        1. POST form credentials to /j_security_check endpoint
+        2. Extract JSESSIONID cookie from response
+        3. Attempt to fetch XSRF token (for 19.2+ only)
+        4. Return session data with TTL
+
+        Args:
+            url: Base URL of the SDWAN Manager (e.g., "https://sdwan-manager.example.com").
+                Should not include trailing slashes or API paths.
+            username: SDWAN Manager username for authentication. This should be a valid
+                user configured with appropriate permissions.
+            password: Password for the specified user account.
+
+        Returns:
+            A tuple containing:
+                - auth_dict (dict): Dictionary with 'jsessionid' (str) and 'xsrf_token'
+                  (str | None). The xsrf_token is None for pre-19.2 versions.
+                - expires_in (int): Session lifetime in seconds (typically 1800).
+
+        Raises:
+            httpx.HTTPStatusError: If SDWAN Manager 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.
+            ValueError: If the JSESSIONID cookie is not received in the response,
+                indicating a malformed or unexpected response.
+
+        Note:
+            SSL verification is disabled (verify=False) to handle self-signed
+            certificates commonly used in lab and development deployments.
+            In production environments, proper certificate validation should be enabled
+            by either installing the certificate in the trust store or providing
+            a custom CA bundle via the verify parameter.
+        """
+        # NOTE: SSL verification is disabled (verify=False) to handle self-signed
+        # certificates commonly used in lab and development deployments.
+        with httpx.Client(verify=False, timeout=AUTH_REQUEST_TIMEOUT_SECONDS) as client:
+            # Step 1: Form-based login to SDWAN Manager
+            auth_response = client.post(
+                f"{url}/j_security_check",
+                data={"j_username": username, "j_password": password},
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                follow_redirects=False,
+            )
+            auth_response.raise_for_status()
+
+            # Validate JSESSIONID cookie was received
+            if "JSESSIONID" not in auth_response.cookies:
+                raise ValueError(
+                    "No JSESSIONID cookie received from SDWAN Manager. "
+                    "This may indicate invalid credentials or a server error. "
+                    f"Response status: {auth_response.status_code}"
+                )
+
+            jsessionid = auth_response.cookies["JSESSIONID"]
+
+            # Step 2: Attempt to get XSRF token (19.2+ only)
+            # Pre-19.2 versions do not require XSRF token, so failures are expected
+            xsrf_token: str | None = None
+            try:
+                token_response = client.get(
+                    f"{url}/dataservice/client/token",
+                    cookies={"JSESSIONID": jsessionid},
+                    timeout=XSRF_TOKEN_FETCH_TIMEOUT_SECONDS,
+                )
+                if token_response.status_code == 200:
+                    xsrf_token = token_response.text.strip()
+            except (httpx.HTTPError, httpx.TimeoutException):
+                # Pre-19.2 does not support XSRF tokens, continue without
+                pass
+
+            return {
+                "jsessionid": jsessionid,
+                "xsrf_token": xsrf_token,
+            }, SDWAN_MANAGER_SESSION_LIFETIME_SECONDS
+
+    @classmethod
+    def get_auth(cls) -> dict[str, Any]:
+        """Get SDWAN Manager authentication data with automatic caching and renewal.
+
+        This is the primary method that consumers should use to obtain SDWAN Manager
+        authentication data. It leverages the AuthCache to efficiently manage
+        session lifecycle, reusing valid sessions and automatically renewing
+        expired ones. This significantly reduces the number of authentication
+        requests to the SDWAN Manager.
+
+        The method uses a cache key based on the controller type ("SDWAN_MANAGER") and
+        URL to ensure proper session isolation between different SDWAN Manager instances.
+
+        Environment Variables Required:
+            SDWAN_URL: Base URL of the SDWAN Manager
+            SDWAN_USERNAME: SDWAN Manager username for authentication
+            SDWAN_PASSWORD: SDWAN Manager password for authentication
+
+        Returns:
+            A dictionary containing:
+                - jsessionid (str): The session cookie value for API requests
+                - xsrf_token (str | None): The XSRF token for CSRF protection
+                  (None for pre-19.2 versions)
+
+        Raises:
+            ValueError: If any required environment variables (SDWAN_URL,
+                SDWAN_USERNAME, SDWAN_PASSWORD) are not set.
+            httpx.HTTPStatusError: If SDWAN Manager 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.
+
+        Example:
+            >>> # Set environment variables first
+            >>> import os
+            >>> os.environ["SDWAN_URL"] = "https://sdwan-manager.example.com"
+            >>> os.environ["SDWAN_USERNAME"] = "admin"
+            >>> os.environ["SDWAN_PASSWORD"] = "password123"
+            >>> # Get authentication data
+            >>> auth_data = SDWANManagerAuth.get_auth()
+            >>> # Use in API requests
+            >>> headers = {"Cookie": f"JSESSIONID={auth_data['jsessionid']}"}
+            >>> if auth_data.get("xsrf_token"):
+            ...     headers["X-XSRF-TOKEN"] = auth_data["xsrf_token"]
+        """
+        url = os.environ.get("SDWAN_URL")
+        username = os.environ.get("SDWAN_USERNAME")
+        password = os.environ.get("SDWAN_PASSWORD")
+
+        if not all([url, username, password]):
+            missing_vars: list[str] = []
+            if not url:
+                missing_vars.append("SDWAN_URL")
+            if not username:
+                missing_vars.append("SDWAN_USERNAME")
+            if not password:
+                missing_vars.append("SDWAN_PASSWORD")
+            raise ValueError(f"Missing required environment variables: {', '.join(missing_vars)}")
+
+        # Normalize URL by removing trailing slash
+        url = url.rstrip("/")  # type: ignore[union-attr]
+
+        def auth_wrapper() -> tuple[dict[str, Any], int]:
+            """Wrapper for authentication that captures closure variables."""
+            return cls._authenticate(url, username, password)  # 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="SDWAN_MANAGER",
+            url=url,
+            auth_func=auth_wrapper,
+        )

nac_test_pyats_common/sdwan/device_resolver.py

@@ -0,0 +1,179 @@
+"""SD-WAN-specific device resolver for parsing the NAC data model.
+
+This module provides the SDWANDeviceResolver class, which extends
+BaseDeviceResolver to implement SD-WAN schema navigation.
+"""
+
+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("SDWAN")
+class SDWANDeviceResolver(BaseDeviceResolver):
+    """SD-WAN device resolver for D2D testing.
+
+    Navigates the SD-WAN NAC schema (sites[].routers[]) to extract
+    device information for SSH testing.
+
+    Schema structure:
+        sdwan:
+          sites:
+            - name: "site1"
+              routers:
+                - chassis_id: "abc123"
+                  device_variables:
+                    system_hostname: "router1"
+                    vpn10_mgmt_ip: "10.1.1.100/32"
+
+    Credentials:
+        Uses IOSXE_USERNAME and IOSXE_PASSWORD environment variables
+        because SD-WAN edge devices are IOS-XE based.
+
+    Example:
+        >>> resolver = SDWANDeviceResolver(data_model)
+        >>> devices = resolver.get_resolved_inventory()
+        >>> for device in devices:
+        ...     print(f"{device['hostname']}: {device['host']}")
+    """
+
+    def get_architecture_name(self) -> str:
+        """Return 'sdwan' as the architecture identifier.
+
+        Returns:
+            Architecture name used in logging and error messages.
+        """
+        return "sdwan"
+
+    def get_schema_root_key(self) -> str:
+        """Return 'sdwan' as the root key in the data model.
+
+        Returns:
+            Root key used when loading test inventory and navigating schema.
+        """
+        return "sdwan"
+
+    def navigate_to_devices(self) -> list[dict[str, Any]]:
+        """Navigate SD-WAN schema: sdwan.sites[].routers[].
+
+        Traverses the SD-WAN data model structure to find all router
+        devices across all sites.
+
+        Returns:
+            List of router dictionaries from all sites.
+        """
+        devices: list[dict[str, Any]] = []
+        sdwan_data = self.data_model.get("sdwan", {})
+
+        for site in sdwan_data.get("sites", []):
+            routers = site.get("routers", [])
+            devices.extend(routers)
+
+        return devices
+
+    def extract_device_id(self, device_data: dict[str, Any]) -> str:
+        """Extract chassis_id as the device identifier.
+
+        Args:
+            device_data: Router data dictionary from the data model.
+
+        Returns:
+            Unique chassis_id string.
+
+        Raises:
+            ValueError: If the router is missing the chassis_id field.
+        """
+        chassis_id = device_data.get("chassis_id")
+        if not chassis_id:
+            raise ValueError("Router missing 'chassis_id' field")
+        return str(chassis_id)
+
+    def extract_hostname(self, device_data: dict[str, Any]) -> str:
+        """Extract hostname from device_variables.system_hostname.
+
+        Looks for system_hostname in the device_variables section.
+        Falls back to chassis_id if system_hostname is not available.
+
+        Args:
+            device_data: Router data dictionary from the data model.
+
+        Returns:
+            Device hostname string.
+        """
+        device_vars = device_data.get("device_variables", {})
+
+        if "system_hostname" in device_vars:
+            return str(device_vars["system_hostname"])
+
+        # Fallback to chassis_id
+        chassis_id = device_data.get("chassis_id", "unknown")
+        logger.warning(f"No system_hostname found for {chassis_id}, using chassis_id as hostname")
+        return str(chassis_id)
+
+    def extract_host_ip(self, device_data: dict[str, Any]) -> str:
+        """Extract management IP from device_variables.
+
+        Handles CIDR notation (e.g., "10.1.1.100/32" -> "10.1.1.100").
+        Uses management_ip_variable field to determine which variable
+        contains the management IP.
+
+        Args:
+            device_data: Router data dictionary from the data model.
+
+        Returns:
+            IP address string without CIDR notation (e.g., "10.1.1.100").
+
+        Raises:
+            ValueError: If no management IP can be found.
+        """
+        device_vars = device_data.get("device_variables", {})
+
+        # Get the variable name that contains the management IP
+        ip_var = device_data.get("management_ip_variable")
+
+        if ip_var and ip_var in device_vars:
+            ip_value = str(device_vars[ip_var])
+        else:
+            # Fallback: try common variable names
+            for fallback_var in ["mgmt_ip", "management_ip", "vpn0_ip"]:
+                if fallback_var in device_vars:
+                    ip_value = str(device_vars[fallback_var])
+                    break
+            else:
+                raise ValueError(
+                    "Could not find management IP for device. "
+                    "Set 'management_ip_variable' in test_inventory or use "
+                    "standard variable names (mgmt_ip, management_ip, vpn0_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:
+        """Extract OS type, defaulting to 'iosxe' for SD-WAN edges.
+
+        Args:
+            device_data: Router data dictionary from the data model.
+
+        Returns:
+            OS type string (e.g., "iosxe", "nxos", "iosxr").
+        """
+        return str(device_data.get("os", "iosxe"))
+
+    def get_credential_env_vars(self) -> tuple[str, str]:
+        """Return IOS-XE credential env vars for SD-WAN edge devices.
+
+        SD-WAN D2D tests connect to IOS-XE based edge devices,
+        NOT the vManage/SDWAN Manager controller.
+
+        Returns:
+            Tuple of (username_env_var, password_env_var).
+        """
+        return ("IOSXE_USERNAME", "IOSXE_PASSWORD")

nac_test_pyats_common/sdwan/ssh_test_base.py

@@ -0,0 +1,101 @@
+"""SD-WAN specific base test class for SSH/Direct-to-Device testing.
+
+This module provides the SDWANTestBase class, which extends the generic SSHTestBase
+to add SD-WAN-specific functionality for device-to-device (D2D) testing.
+
+The class delegates device inventory resolution to SDWANDeviceResolver, which
+handles all SD-WAN schema navigation and credential injection.
+
+Credentials:
+    SD-WAN D2D tests connect to IOS-XE based edge devices, NOT the SDWAN Manager
+    controller. Set these environment variables:
+    - IOSXE_USERNAME: SSH username for edge devices
+    - IOSXE_PASSWORD: SSH password for edge 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 SDWANDeviceResolver
+
+logger = logging.getLogger(__name__)
+
+
+class SDWANTestBase(SSHTestBase):  # type: ignore[misc]
+    """SD-WAN-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 SDWANDeviceResolver.
+
+    Credentials:
+        SD-WAN D2D tests require IOSXE_USERNAME and IOSXE_PASSWORD environment
+        variables (NOT SDWAN_* which are for the controller).
+
+    Example:
+        class MySDWANSSHTest(SDWANTestBase):
+            @aetest.test
+            def verify_device_connectivity(self, steps, device):
+                # SSH-based verification logic here
+                pass
+    """
+
+    @classmethod
+    def get_ssh_device_inventory(cls, data_model: dict[str, Any]) -> list[dict[str, Any]]:
+        """Parse the SD-WAN 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 SDWANDeviceResolver,
+        which handles:
+        - Test inventory loading (test_inventory.yaml)
+        - Schema navigation (sites[].routers[])
+        - Variable resolution (hostnames, IPs)
+        - Credential injection (IOSXE_USERNAME, IOSXE_PASSWORD)
+
+        Args:
+            data_model: The merged data model from nac-test containing all
+                sites.nac.yaml 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 (chassis_id)
+
+        Raises:
+            ValueError: If IOSXE_USERNAME or IOSXE_PASSWORD env vars are not set.
+        """
+        logger.info("SDWANTestBase: Resolving device inventory via SDWANDeviceResolver")
+
+        # Delegate entirely to the resolver
+        # SDWANDeviceResolver handles:
+        # 1. Test inventory loading via BaseDeviceResolver._load_inventory()
+        # 2. Schema navigation via navigate_to_devices()
+        # 3. Credential injection via _inject_credentials() using IOSXE_* env vars
+        resolver = SDWANDeviceResolver(data_model)
+        return resolver.get_resolved_inventory()
+
+    def get_device_credentials(self, device: dict[str, Any]) -> dict[str, str | None]:
+        """Get SD-WAN edge device SSH credentials from environment variables.
+
+        SD-WAN D2D tests connect to IOS-XE edge devices (vEdge, ISR, etc.),
+        NOT the SDWAN Manager 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"),
+        }