catalystwan 0.41.5.dev8__tar.gz → 0.41.6.dev1__tar.gz

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: catalystwan
-Version: 0.41.5.dev8
+Version: 0.41.6.dev1
 Summary: Cisco Catalyst WAN SDK for Python
 Author: sbasan
 Author-email: sbasan@cisco.com

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/api/basic_api.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import logging
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Iterator, List, Union
+from typing import TYPE_CHECKING, Any, Iterator, List, Optional, Union
 
 from tenacity import retry, retry_if_result, stop_after_attempt, wait_fixed  # type: ignore
 
@@ -134,11 +134,104 @@ class DevicesAPI:
 
         return True if wait_for_state() else False
 
-    def get(self, rediscover: bool = False) -> DataSequence[Device]:
+    @staticmethod
+    def _first_present(*values: Any) -> Optional[str]:
+        for value in values:
+            if value is not None and value != "":
+                return str(value)
+        return None
+
+    @classmethod
+    def _device_from_inventory(cls, device_details) -> Device:
+        device_id = cls._first_present(
+            getattr(device_details, "device_id", None),
+            getattr(device_details, "device_ip", None),
+            getattr(device_details, "system_ip", None),
+            getattr(device_details, "management_system_ip", None),
+            getattr(device_details, "local_system_ip", None),
+        )
+        uuid = cls._first_present(getattr(device_details, "uuid", None), getattr(device_details, "chasis_number", None))
+        hostname = cls._first_present(
+            getattr(device_details, "host_name", None),
+            getattr(device_details, "ncs_device_name", None),
+            device_id,
+        )
+        local_system_ip = cls._first_present(
+            getattr(device_details, "local_system_ip", None),
+            getattr(device_details, "system_ip", None),
+            getattr(device_details, "device_ip", None),
+            device_id,
+        )
+
+        if device_id is None or uuid is None or hostname is None or local_system_ip is None:
+            raise ValueError(f"Incomplete device inventory entry: {device_details!r}")
+
+        return create_dataclass(
+            Device,
+            {
+                "uuid": uuid,
+                "personality": cls._first_present(getattr(device_details, "personality", None), Personality.EDGE.value),
+                "id": device_id,
+                "hostname": hostname,
+                "reachability": cls._first_present(
+                    getattr(device_details, "reachability", None), Reachability.UNKNOWN.value
+                ),
+                "local_system_ip": local_system_ip,
+                "status": cls._first_present(
+                    getattr(device_details, "device_state", None),
+                    getattr(device_details, "state", None),
+                    getattr(device_details, "validity", None),
+                ),
+                "model": cls._first_present(
+                    getattr(device_details, "device_model", None),
+                    getattr(device_details, "device_type", None),
+                ),
+                "site_id": cls._first_present(
+                    getattr(device_details, "site_id", None),
+                    getattr(device_details, "configured_site_id", None),
+                ),
+                "site_name": getattr(device_details, "site_name", None),
+            },
+        )
+
+    def _get_unmonitored_wan_edges(self, known_devices: DataSequence[Device]) -> DataSequence[Device]:
+        known_device_keys = {
+            value
+            for device in known_devices
+            for value in (device.uuid, device.id, device.hostname, device.local_system_ip)
+            if value
+        }
+        wan_edges = DataSequence(Device, [])
+
+        try:
+            device_details = self.session.endpoints.configuration_device_inventory.get_device_details("vedges")
+        except CatalystwanException as exc:
+            logger.debug("Skipping WAN edge inventory lookup: %s", exc)
+            return wan_edges
+
+        if not isinstance(device_details, DataSequence):
+            return wan_edges
+
+        for device_detail in device_details:
+            try:
+                device = self._device_from_inventory(device_detail)
+            except ValueError as exc:
+                logger.debug("Skipping WAN edge inventory entry: %s", exc)
+                continue
+
+            device_keys = {device.uuid, device.id, device.hostname, device.local_system_ip}
+            if device_keys.isdisjoint(known_device_keys):
+                wan_edges.append(device)
+                known_device_keys.update(device_keys)
+
+        return wan_edges
+
+    def get(self, rediscover: bool = False, include_inventory: bool = True) -> DataSequence[Device]:
         """Data sequence of all devices.
 
         Args:
             rediscover: Rediscover device request payload
+            include_inventory: Include WAN edge inventory entries that are not currently returned by device monitoring
 
         Returns:
             DataSequence[Device] of all devices
@@ -161,6 +254,9 @@ class DevicesAPI:
             resp = self.session.get(url="/dataservice/device/system/info", params=params)
             devices_sys_info += resp.dataseq(Device)
 
+        if include_inventory:
+            devices_sys_info += self._get_unmonitored_wan_edges(devices_sys_info)
+
         return devices_sys_info
 
 

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/api/template_api.py

@@ -45,7 +45,12 @@ from catalystwan.api.templates.models.vpn_vsmart_interface_model import VpnVsmar
 from catalystwan.api.templates.models.vpn_vsmart_model import VpnVsmartModel
 from catalystwan.dataclasses import Device, FeatureTemplatesTypes
 from catalystwan.endpoints.configuration_device_template import FeatureToCLIPayload
-from catalystwan.exceptions import AttachedError, CatalystwanDeprecationWarning, TemplateNotFoundError
+from catalystwan.exceptions import (
+    AttachedError,
+    CatalystwanDeprecationWarning,
+    InvalidOperationError,
+    TemplateNotFoundError,
+)
 from catalystwan.models.common import DeviceModel
 from catalystwan.models.templates import DeviceTemplateInformation, FeatureTemplateInformation, TemplateInformation
 from catalystwan.response import ManagerResponse
@@ -82,16 +87,13 @@ class TemplatesAPI:
         self.session = session
 
     @overload
-    def get(self, template: Type[DeviceTemplate]) -> DataSequence[DeviceTemplateInformation]:
-        ...
+    def get(self, template: Type[DeviceTemplate]) -> DataSequence[DeviceTemplateInformation]: ...
 
     @overload
-    def get(self, template: Type[FeatureTemplate]) -> DataSequence[FeatureTemplateInformation]:
-        ...
+    def get(self, template: Type[FeatureTemplate]) -> DataSequence[FeatureTemplateInformation]: ...
 
     @overload
-    def get(self, template: Type[CLITemplate]) -> DataSequence[TemplateInformation]:
-        ...
+    def get(self, template: Type[CLITemplate]) -> DataSequence[TemplateInformation]: ...
 
     def get(self, template):
         if isinstance(template, FeatureTemplate):
@@ -122,10 +124,13 @@ class TemplatesAPI:
             params={"feature": feature.value}
         )
 
-    def attach(self, name: str, device: Device, timeout_seconds: int = 300, **kwargs):
+    def attach(self, name: str, device: Optional[Device], timeout_seconds: int = 300, **kwargs):
         template_info = self.get(DeviceTemplate).filter(name=name).single_or_default()
         if not template_info:
-            raise TemplateNotFoundError(f"Template with name [{name}] does not exists.")
+            raise TemplateNotFoundError(name)
+
+        if device is None:
+            raise InvalidOperationError(f"Device is required to attach template '{name}'.")
 
         if template_info.config_type == TemplateType.CLI.value:
             return self._attach_cli(name, device, timeout_seconds=timeout_seconds, **kwargs)
@@ -159,6 +164,7 @@ class TemplatesAPI:
             values = self.session.post(endpoint, json=body).json()["header"]["columns"]
             return [DeviceSpecificValue(**value) for value in values]
 
+        device_specific_vars = kwargs.get("device_specific_vars", {})
         vars = get_device_specific_variables(name)
         template_id = self.get(DeviceTemplate).filter(name=name).single_or_default().id
         payload = {
@@ -183,12 +189,12 @@ class TemplatesAPI:
         for var in vars:
             if var.property not in payload["deviceTemplateList"][0]["device"][0]:
                 pointer = payload["deviceTemplateList"][0]["device"][0]
-                if var.property not in kwargs["device_specific_vars"]:
+                if var.property not in device_specific_vars:
                     invalid = True
                     msg[var.property] = "should be provided in attach method as device_specific_vars kwarg."
                     logger.error(f"{var.property} should be provided in attach method as device_specific_vars kwarg.")
                 else:
-                    pointer[var.property] = kwargs["device_specific_vars"][var.property]  # type: ignore
+                    pointer[var.property] = device_specific_vars[var.property]  # type: ignore
 
         if invalid:
             raise TypeError(f"{msg}")

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/dataclasses.py

@@ -178,10 +178,15 @@ class BfdSessionData(DataclassBase):
     destinationPublicIp: str = field(metadata={FIELD_NAME: "dst-ip"})
 
 
+def _remove_omp_peer_prefix(value: str, prefix: str) -> str:
+    """Normalize OMP peer enum values returned by different SD-WAN versions."""
+    return value[len(prefix) :] if value.startswith(prefix) else value
+
+
 @define
 class OmpPeerData(DataclassBase):
-    type: str
-    state: str
+    type: str = field(converter=lambda value: _remove_omp_peer_prefix(value, "device-"))
+    state: str = field(converter=lambda value: _remove_omp_peer_prefix(value, "peer-state-"))
     peerIp: str = field(metadata={FIELD_NAME: "peer"})
     siteId: str = field(metadata={FIELD_NAME: "site-id"})
     domainId: str = field(metadata={FIELD_NAME: "domain-id"})

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/endpoints/configuration_device_inventory.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Dict, List, Literal, Optional, Union
 from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 from catalystwan.endpoints import APIEndpoints, CustomPayloadType, PreparedPayload, delete, get, post, versions
 from catalystwan.typed_list import DataSequence
@@ -63,6 +63,7 @@ class DeviceDetailsResponse(BaseModel):
     model_config = ConfigDict(populate_by_name=True, protected_namespaces=())
 
     device_type: Optional[str] = Field(default=None, validation_alias="deviceType", serialization_alias="deviceType")
+    device_id: Optional[str] = Field(default=None, validation_alias="deviceId", serialization_alias="deviceId")
     serial_number: Optional[str] = Field(
         default=None, validation_alias="serialNumber", serialization_alias="serialNumber"
     )
@@ -76,7 +77,9 @@ class DeviceDetailsResponse(BaseModel):
     config_operation_mode: Optional[str] = Field(
         default=None, validation_alias="configOperationMode", serialization_alias="configOperationMode"
     )
-    device_model: Optional[str] = Field(default=None, validation_alias="deviceModel", serialization_alias="deviceModel")
+    device_model: Optional[str] = Field(
+        default=None, validation_alias=AliasChoices("deviceModel", "device-model"), serialization_alias="deviceModel"
+    )
     device_state: Optional[str] = Field(default=None, validation_alias="deviceState", serialization_alias="deviceState")
     validity: Optional[str] = None
     platform_family: Optional[str] = Field(
@@ -169,12 +172,20 @@ class DeviceDetailsResponse(BaseModel):
     )
     domain_id: Optional[str] = Field(default=None, validation_alias="domain-id", serialization_alias="domain-id")
     local_system_ip: Optional[str] = Field(
-        default=None, validation_alias="local-system-ip", serialization_alias="ocal-system-ip"
+        default=None,
+        validation_alias=AliasChoices("local-system-ip", "localSystemIp", "localSystemIP"),
+        serialization_alias="local-system-ip",
+    )
+    system_ip: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("system-ip", "systemIp", "systemIP"),
+        serialization_alias="system-ip",
     )
-    system_ip: Optional[str] = Field(default=None, validation_alias="system-ip", serialization_alias="system-ip")
     model_sku: Optional[str] = Field(default=None)
     site_id: Optional[str] = Field(default=None, validation_alias="site-id", serialization_alias="site-id")
-    host_name: Optional[str] = Field(default=None, validation_alias="host-name", serialization_alias="host-name")
+    host_name: Optional[str] = Field(
+        default=None, validation_alias=AliasChoices("host-name", "hostName"), serialization_alias="host-name"
+    )
     sp_organization_name: Optional[str] = Field(
         default=None, validation_alias="sp-organization-name", serialization_alias="sp-organization-name"
     )

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/models/configuration/feature_profile/sdwan/sig_security/sig_security.py

@@ -16,7 +16,15 @@ TunnelDcPreference = Literal["primary-dc", "secondary-dc"]
 IkeGroup = Literal["2", "5", "14", "15", "16", "19", "20", "21"]
 IpsecReplayWindow = Literal[64, 128, 256, 512, 1024]
 IpsecCiphersuite = Literal[
-    "aes256-cbc-sha1", "aes256-cbc-sha384", "aes256-cbc-sha256", "aes256-cbc-sha512", "aes256-gcm"
+    "aes256-cbc-sha1",
+    "aes256-cbc-sha384",
+    "aes256-cbc-sha256",
+    "aes256-cbc-sha512",
+    "aes256-gcm",
+    "null-sha1",
+    "null-sha384",
+    "null-sha256",
+    "null-sha512",
 ]
 PerfectForwardSecrecy = Literal[
     "group-2", "group-5", "group-14", "group-15", "group-16", "group-19", "group-20", "group-21", "none"
@@ -41,7 +49,9 @@ class Interface(BaseModel):
         serialization_alias="ifName", validation_alias="ifName", description="Interface name: IPsec when present"
     )
     auto: Optional[Global[bool]] = Field(default=None, description="Auto Tunnel Mode")
-    shutdown: Union[Global[bool], Default[bool]] = Field(default=as_default(False), description="Administrative state")
+    shutdown: Union[Global[bool], Default[bool], Variable] = Field(
+        default=as_default(False), description="Administrative state"
+    )
     description: Optional[Union[Global[str], Variable, Default[None]]] = Field(
         default=None, description="Interface description"
     )

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/models/configuration/feature_profile/sdwan/system/ntp.py

@@ -43,14 +43,26 @@ class AuthenticationVariable(BaseModel):
     key_id: Union[Variable, Global[int]] = Field(
         ..., serialization_alias="keyId", validation_alias="keyId", description="MD5 authentication key ID"
     )
-    md5_value: Union[Variable, Global[str]] = Field(
-        ...,
+    md5_value: Optional[Union[Variable, Global[str]]] = Field(
+        default=None,
         serialization_alias="md5Value",
         validation_alias="md5Value",
         description="Enter cleartext or AES-encrypted MD5 authentication key"
         "[Note: Catalyst SD-WAN Manager will encrypt this field before saving."
         "Cleartext strings will not be returned back to the user in GET responses for sensitive fields.]",
     )
+    hmac_sha2_256_value: Optional[Union[Variable, Global[str]]] = Field(
+        default=None,
+        serialization_alias="hmacSha2Value",
+        validation_alias="hmacSha2Value",
+        description="HMAC-SHA2-256 (digest length = 256 bits, key length = [1-32] bytes)",
+    )
+    cmac_aes_128_value: Optional[Union[Variable, Global[str]]] = Field(
+        default=None,
+        serialization_alias="cmacAes128Value",
+        validation_alias="cmacAes128Value",
+        description="CMAC-AES-128 (digest length = 128 bits, key length = [16 or 32] bytes)",
+    )
 
 
 class Authentication(BaseModel):
@@ -62,7 +74,7 @@ class Authentication(BaseModel):
         default_factory=list,
         serialization_alias="authenticationKeys",
         validation_alias="authenticationKeys",
-        description="Set MD5 authentication key",
+        description="Set MD5, HMAC-SHA2-256, CMAC-AES-128 authentication key",
     )
     trusted_keys: Optional[Union[Variable, Global[List[int]], Default[None]]] = Field(
         None,

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/tests/test_devices_api.py

@@ -9,6 +9,7 @@ from tenacity import RetryError  # type: ignore
 
 from catalystwan.api.basic_api import DevicesAPI, DeviceStateAPI
 from catalystwan.dataclasses import BfdSessionData, Connection, Device, WanInterface
+from catalystwan.endpoints.configuration_device_inventory import DeviceDetailsResponse
 from catalystwan.endpoints.endpoints_container import APIEndpointContainter
 from catalystwan.endpoints.monitoring.device_details import DeviceData
 from catalystwan.endpoints.real_time_monitoring.reboot_history import RebootEntry
@@ -17,6 +18,7 @@ from catalystwan.response import ManagerResponse
 from catalystwan.typed_list import DataSequence
 from catalystwan.utils.creation_tools import create_dataclass
 from catalystwan.utils.personality import Personality
+from catalystwan.utils.reachability import Reachability
 
 
 class ResponseMock:
@@ -118,6 +120,32 @@ class TestDevicesAPI(TestCase):
         self.system_ips_list = [device["local-system-ip"] for device in self.devices]
         self.ips_list = [device["deviceId"] for device in self.devices]
         self.list_all_devices_resp = DataSequence(DeviceData, [DeviceData.model_validate(dev) for dev in self.devices])
+        self.inventory_edge = DeviceDetailsResponse.model_validate(
+            {
+                "uuid": "dddddddd-6169-445c-8e49-c0bdaaaaaaa",
+                "deviceIP": "169.254.10.81",
+                "host-name": "vm81",
+                "personality": "vedge",
+                "local-system-ip": "169.254.10.81",
+                "deviceModel": "vedge-C8000V",
+                "site-id": "81",
+                "deviceState": "valid",
+            }
+        )
+        self.inventory_edge_dataclass = create_dataclass(
+            Device,
+            {
+                "uuid": "dddddddd-6169-445c-8e49-c0bdaaaaaaa",
+                "personality": Personality.EDGE,
+                "id": "169.254.10.81",
+                "hostname": "vm81",
+                "reachability": Reachability.UNKNOWN,
+                "local_system_ip": "169.254.10.81",
+                "status": "valid",
+                "model": "vedge-C8000V",
+                "site_id": "81",
+            },
+        )
 
     @patch("catalystwan.response.ManagerResponse")
     @patch("catalystwan.session.ManagerSession")
@@ -199,6 +227,28 @@ class TestDevicesAPI(TestCase):
         # Assert
         self.assertEqual(answer, self.devices_dataseq)
 
+    @patch("catalystwan.response.ManagerResponse")
+    @patch("catalystwan.session.ManagerSession")
+    def test_get_includes_unmonitored_wan_edge_inventory(self, mock_session, mock_response):
+        # Arrange
+        mock_session.get.return_value = mock_response
+        mock_session.endpoints.monitoring_device_details.list_all_devices.return_value = DataSequence(
+            DeviceData, [DeviceData.model_validate(self.devices[0])]
+        )
+        mock_session.endpoints.configuration_device_inventory.get_device_details.return_value = DataSequence(
+            DeviceDetailsResponse, [self.inventory_edge]
+        )
+        mock_response.dataseq.return_value = DataSequence(Device, [create_dataclass(Device, self.devices[0])])
+
+        # Act
+        answer = DevicesAPI(mock_session).get()
+
+        # Assert
+        self.assertEqual(
+            answer,
+            DataSequence(Device, [create_dataclass(Device, self.devices[0]), self.inventory_edge_dataclass]),
+        )
+
     @parameterized.expand(
         [
             ["aaaaaaaa-6169-445c-8e49-c0bdaaaaaaa", 0],

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/tests/test_omp_api.py

@@ -25,6 +25,31 @@ class TestOmpAPI(unittest.TestCase):
         answer = OmpAPI(mock_session).get_omp_peers(self.device_id)
         # Assert
         self.assertEqual(answer, self.omp_peer_dataclass)
+        self.assertEqual(answer[0].type, "vsmart")
+        self.assertEqual(answer[0].state, "up")
+
+    @patch("catalystwan.session.Session")
+    def test_omp_peers_normalizes_prefixed_values(self, mock_session):
+        # Arrange
+        mock_session.get_data.return_value = [
+            {
+                **self.omp_peer[0],
+                "type": "device-vsmart",
+                "state": "peer-state-up",
+            },
+            {
+                **self.omp_peer[1],
+                "type": "device-vsmart",
+                "state": "peer-state-down",
+            },
+        ]
+        # Act
+        answer = OmpAPI(mock_session).get_omp_peers(self.device_id)
+        # Assert
+        self.assertEqual(answer[0].type, "vsmart")
+        self.assertEqual(answer[0].state, "up")
+        self.assertEqual(answer[1].type, "vsmart")
+        self.assertEqual(answer[1].state, "down")
 
     @patch("catalystwan.session.Session")
     def test_omp_peers_empty(self, mock_session):

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/catalystwan/tests/test_templates.py

@@ -14,6 +14,7 @@ from catalystwan.api.templates.models.cisco_aaa_model import CiscoAAAModel
 from catalystwan.api.templates.payloads.aaa.aaa_model import AAAModel, AuthenticationOrder
 from catalystwan.dataclasses import Device
 from catalystwan.endpoints.configuration_template_master import DeviceTemplateInformation
+from catalystwan.exceptions import InvalidOperationError, TemplateNotFoundError
 from catalystwan.typed_list import DataSequence
 from catalystwan.utils.personality import Personality
 from catalystwan.utils.reachability import Reachability
@@ -258,6 +259,30 @@ class TestTemplatesAPI(unittest.TestCase):
         assert not mock_create_feature_template.called
         assert not mock_create_by_generator.called
 
+    @patch("catalystwan.session.ManagerSession")
+    def test_attach_missing_template_raises_template_not_found(self, mock_session):
+        mock_session.endpoints.configuration_template_master.get_device_template_list.return_value = DataSequence(
+            DeviceTemplateInformation, []
+        )
+
+        templates_api = TemplatesAPI(mock_session)
+
+        with self.assertRaises(TemplateNotFoundError):
+            templates_api.attach("missing_template", self.device_info)
+
+    @patch("catalystwan.session.ManagerSession")
+    def test_attach_missing_device_raises_invalid_operation(self, mock_session):
+        # Arrange
+        mock_session.get.return_value.dataseq.return_value = DataSequence(
+            DeviceTemplateInformation,
+            [DeviceTemplateInformation.model_validate(self.data_template[0])],
+        )
+        templates_api = TemplatesAPI(mock_session)
+
+        # Act / Assert
+        with self.assertRaises(InvalidOperationError):
+            templates_api.attach("template_1", None)
+
     # @patch.object(TemplatesAPI, "templates")
     # @patch("catalystwan.api.template_api.wait_for_completed")
     # @patch("catalystwan.session.ManagerSession")

{catalystwan-0.41.5.dev8 → catalystwan-0.41.6.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "catalystwan"
-version = "0.41.5dev8"
+version = "0.41.6dev1"
 description = "Cisco Catalyst WAN SDK for Python"
 authors = ["sbasan <sbasan@cisco.com>"]
 readme = "README.md"