centralcli 4.0.2__tar.gz → 4.2.0__tar.gz

{centralcli-4.0.2 → centralcli-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: centralcli
-Version: 4.0.2
+Version: 4.2.0
 Summary: A CLI for interacting with Aruba Central (Cloud Management Platform).  Facilitates bulk imports, exports, reporting.  A handy tool if you have devices managed by Aruba Central.
 Home-page: https://github.com/Pack3tL0ss/central-api-cli
 License: MIT

{centralcli-4.0.2 → centralcli-4.2.0}/centralcli/__init__.py

@@ -8,6 +8,7 @@ import os
 import typer
 
 from pathlib import Path
+from typing import Iterable, List
 import sys
 
 import click
@@ -63,6 +64,61 @@ log = MyLogger(log_file, debug=config.debug, show=config.debug, verbose=config.d
 log.debug(f"{__name__} __init__ calling script: {_calling_script}, base_dir: {config.base_dir}")
 log.debugv(f"config attributes: {json.dumps({k: str(v) for k, v in config.__dict__.items()}, indent=4)}")
 
+
+# HACK completion has gotten jacked up.  typer calls click.utils._expand_args in Windows which was added in click 8, but completion is broken in click 8 so cencli is pinned to 7.1.2 until I can investigate further
+# This hack manually adds the _expand_args functionality to click.utils which is pinned to 7.1.2  Otherwise an exception is thrown on Windows.
+if os.name == "nt":  # pragma: no cover
+    def _expand_args(
+        args: Iterable[str],
+        *,
+        user: bool = True,
+        env: bool = True,
+        glob_recursive: bool = True,
+    ) -> List[str]:
+        """Simulate Unix shell expansion with Python functions.
+
+        See :func:`glob.glob`, :func:`os.path.expanduser`, and
+        :func:`os.path.expandvars`.
+
+        This is intended for use on Windows, where the shell does not do any
+        expansion. It may not exactly match what a Unix shell would do.
+
+        :param args: List of command line arguments to expand.
+        :param user: Expand user home directory.
+        :param env: Expand environment variables.
+        :param glob_recursive: ``**`` matches directories recursively.
+
+        :meta private:
+        """
+        from glob import glob
+        import re
+
+        out = []
+
+        for arg in args:
+            if user:
+                arg = os.path.expanduser(arg)
+
+            if env:
+                arg = os.path.expandvars(arg)
+
+            try:
+                matches = glob(arg, recursive=glob_recursive)
+            except re.error:
+                matches = []
+
+            if not matches:
+                out.append(arg)
+            else:
+                out.extend(matches)
+
+        return out
+
+    import click
+    if not hasattr(click.utils, "_expand_args"):
+        click.utils._expand_args = _expand_args
+
+
 from pycentral.base import ArubaCentralBase
 from .utils import Utils
 utils = Utils()

{centralcli-4.0.2 → centralcli-4.2.0}/centralcli/caas.py

@@ -128,8 +128,6 @@ class BuildCLI:
             common = self.data[dev]["_common"]
             vlans = self.data[dev]["vlans"]
             _pretty_name = typer.style(common.get('hostname', dev), fg="bright_green")
-            # print(f"Verifying {_pretty_name} is in Group {common['group']}...", end='')
-            # group_devs = self.session.get_gateways_by_group(self.data[dev]["_common"]["group"])
             resp = self.central.request(self.central.get_devices, "gateways")
             gateways = resp.output
             self.dev_info = [_dev for _dev in gateways if _dev.get('mac', '').lower() == dev.lower()]

{centralcli-4.0.2 → centralcli-4.2.0}/centralcli/cache.py

@@ -590,7 +590,7 @@ class Cache:
         incomplete: str,
         args: List[str] = [],
     ) -> Generator[Tuple[str, str], None, None] | None:
-        """Device completion for returning matches that are either switch or AP
+        """Device completion for returning matches that are switches (AOS-SW or CX)
 
         Args:
             incomplete (str): The last partial or full command before completion invoked.
@@ -617,6 +617,40 @@ class Cache:
         for m in out:
             yield m
 
+    # TODO this is not used until get_dev_identifier is refactored to support type vs generic_type
+    # TODO Also args is not being sent by typer, would need to use ctx.params.values()
+    # def dev_cx_completion(
+    #     self,
+    #     incomplete: str,
+    #     args: List[str] = [],
+    # ) -> Generator[Tuple[str, str], None, None] | None:
+    #     """Device completion for returning matches that are CX switches
+
+    #     Args:
+    #         incomplete (str): The last partial or full command before completion invoked.
+    #         args (List[str], optional): The previous arguments/commands on CLI. Defaults to [].
+
+    #     Yields:
+    #         Generator[Tuple[str, str], None, None]: Name and help_text for the device, or
+    #             Returns None if config is invalid
+    #     """
+    #     # Prevents exception during completion when config missing or invalid
+    #     if not config.valid:
+    #         err_console.print(":warning:  Invalid config")
+    #         return
+
+    #     match = self.get_dev_identifier(incomplete, dev_type=["cx"], completion=True)
+
+    #     out = []
+    #     if match:
+    #         out = [
+    #             tuple([m.name, m.help_text]) for m in sorted(match, key=lambda i: i.name)
+    #             if m.name not in args
+    #             ]
+
+    #     for m in out:
+    #         yield m
+
     def dev_kwarg_completion(
         self,
         ctx: typer.Context,
@@ -810,6 +844,7 @@ class Cache:
 
     def dev_ap_gw_completion(
         self,
+        ctx: typer.Context,
         incomplete: str,
         args: List[str] = None,
     ) -> Generator[Tuple[str, str], None, None] | None:
@@ -828,6 +863,10 @@ class Cache:
             err_console.print(":warning:  Invalid config")
             return
 
+        # Prevents device completion for cencli show config cencli
+        if ctx.command_path == "cencli show config" and ctx.params.get("group_dev", "") == "cencli":
+            return
+
         dev_types = ["ap", "gw"]
         _match = self.get_dev_identifier(incomplete, dev_type=dev_types, completion=True)
 
@@ -912,6 +951,7 @@ class Cache:
     # works in BASH and powershell
     def group_dev_ap_gw_completion(
         self,
+        ctx: typer.Context,
         incomplete: str,
         args: List[str] = None,
     ) -> Generator[Tuple[str, str], None, None] | None:
@@ -945,12 +985,16 @@ class Cache:
                 out += [tuple([m.name, m.help_text])]
                 # out += [tuple([m.name if " " not in m.name else f"'{m.name}'", m.help_text])]  # FIXME completion for names with spaces is now broken, used to work.  Change in completion behavior
 
-        # FIXME args is now always [] believe this came with click 8
-        args = [] if args is None else args
-        if " ".join(args).lower() == "show config" and "cencli".lower().startswith(incomplete):
-            out += [("cencli", "show cencli configuration")]
-        if " ".join(args).lower() == "update config" and "cencli".lower().startswith(incomplete):
-            out += [("cencli", "update cencli configuration")]
+        if args:
+            if " ".join(args).lower() == "show config" and "cencli".lower().startswith(incomplete):
+                out += [("cencli", "show cencli configuration")]
+            if " ".join(args).lower() == "update config" and "cencli".lower().startswith(incomplete):
+                out += [("cencli", "update cencli configuration")]
+        elif ctx.command_path == "cencli show config" and ctx.params.get("group_dev") is None:  # typer not sending args fix
+            if "cencli".lower().startswith(incomplete):
+                out += [("cencli", "update cencli configuration")]
+
+
 
         # partial completion by serial: out appears to have list with expected tuple but does
         # not appear in zsh
@@ -1160,8 +1204,8 @@ class Cache:
                     out += [tuple([c.name, f'{c.ip}|{c.mac} type: {c.type} connected to: {c.connected_name} ~ {c.connected_port} (fail-safe match)'])]
 
 
-        for c in out:
-            yield c
+        for c in out:  # TODO completion behavior has changed.  This works-around issue bash doesn't complete past 00: and zsh treats each octet as a dev name when : is used.
+            yield c[0].replace(":", "-"), c[1]
 
     def event_completion(
         self,
@@ -1183,9 +1227,17 @@ class Cache:
             err_console.print(":warning:  Invalid config")
             return
 
-        for event in self.events:
-            if event["id"].startswith(incomplete):
-                yield event["id"], f"{event['id']}|{event['device'].split('Group:')[0].rstrip()}"
+        if incomplete == "":
+            out = [("cencli", "Show cencli logs"), *[(x['id'], f"{x['id']}|{x['device'].split('Group:')[0].rstrip()}") for x in self.events]]
+            for m in out:
+                yield m[0], m[1]
+
+        elif "cencli".startswith(incomplete.lower()):
+            yield "cencli", "Show cencli logs"
+        else:
+            for event in self.events:
+                if event["id"].startswith(incomplete):
+                    yield event["id"], f"{event['id']}|{event['device'].split('Group:')[0].rstrip()}"
 
     # TODO add support for zip code city state etc.
     def site_completion(
@@ -1356,6 +1408,7 @@ class Cache:
             for m in out:
                 yield m
 
+    # TODO double check not used and remove
     def completion(
         self,
         incomplete: str,
@@ -1428,6 +1481,21 @@ class Cache:
 
         return len(ret) == len(data)
 
+    async def get_swack_ids(self, resp: Response, update_data: List[dict]) -> List[dict]:
+        # TODO these likely cause more delay on large accounts as it's pulling from raw, make more efficient or loop for both aps/switches in the same loop
+        # add swarm_ids for APs to cache (AOS 8 IAP and AP individual Upgrade)
+        if "aps" in resp.raw.get("aps", [{}])[0]:
+            _swarm_ids = {d["serial"]: d["swarm_id"] or d["serial"] for d in resp.raw["aps"][0]["aps"]}
+            update_data = [d if not d["type"] == "ap" or d["serial"] not in _swarm_ids else {**d, **{"swack_id": _swarm_ids[d["serial"]]}} for d in update_data]
+
+        # add stack_ids for switches to cache
+        if "switches" in resp.raw.get("switches", [{}])[0]:
+            _stack_ids = {d["serial"]: d["stack_id"] for d in resp.raw["switches"][0]["switches"]}
+            update_data = [d if d["type"] not in  ["cx", "sw"] or d["serial"] not in _stack_ids else {**d, **{"swack_id": _stack_ids[d["serial"]]}} for d in update_data]
+        # FIXME need to update everything that uses AP swarm_id to use swack_id (swarm/stack id)
+
+        return update_data
+
     # FIXME handle no devices in Central yet exception 837 --> cleaner.py 498
     # TODO if we are updating inventory we only need to get those devices types
     async def update_dev_db(self,  data: Union[str, List[str], List[dict]] = None, remove: bool = False) -> Union[List[int], Response]:
@@ -1487,20 +1555,8 @@ class Cache:
             if resp.ok:
                 if resp.output:
                     _update_data = utils.listify(resp.output)
-                    _update_data = cleaner.get_devices(_update_data)
-
-                    # TODO these likely cause more delay on large accounts as it's pulling from raw, make more efficient or loop for both aps/switches in the same loop
-                    # add swarm_ids for APs to cache (AOS 8 IAP and AP individual Upgrade)
-                    if "aps" in resp.raw.get("aps", [{}])[0]:
-                        _swarm_ids = {d["serial"]: d["swarm_id"] or d["serial"] for d in resp.raw["aps"][0]["aps"]}
-                        _update_data = [d if not d["type"] == "ap" or d["serial"] not in _swarm_ids else {**d, **{"swack_id": _swarm_ids[d["serial"]]}} for d in _update_data]
-
-                    # add stack_ids for switches to cache
-                    if "switches" in resp.raw.get("switches", [{}])[0]:
-                        _stack_ids = {d["serial"]: d["stack_id"] for d in resp.raw["switches"][0]["switches"]}
-                        _update_data = [d if d["type"] not in  ["cx", "sw"] or d["serial"] not in _stack_ids else {**d, **{"swack_id": _stack_ids[d["serial"]]}} for d in _update_data]
-                    # FIXME need to update everything that uses AP swarm_id to use swack_id (swarm/stack id)
-
+                    _update_data = cleaner.get_devices(_update_data, cache=True)
+                    _update_data = await self.get_swack_ids(resp, _update_data)
 
                     self.DevDB.truncate()
                     update_res = self.DevDB.insert_multiple(_update_data)
@@ -2580,6 +2636,7 @@ class Cache:
             else:
                 return None
 
+    # cencli completion can be removed..  Moved to get_event_identifier
     def get_log_identifier(self, query: str) -> str:
         if "audit_trail" in query:
             return query
@@ -2587,7 +2644,6 @@ class Cache:
             return ["cencli", *[x["id"] for x in self.logs]]
 
         try:
-
             if "cencli".startswith(query.lower()):
                 return ["cencli"]
 
@@ -2622,7 +2678,7 @@ class Cache:
                 return match[-1]["details"]
 
         except ValueError as e:
-            log.error(f"Exception in get_event_identifier {e.__class__.__name__}")
+            log.error(f"Exception in get_event_identifier {e.__class__.__name__}", show=True)
             log.exception(e)
-            print(f"[bright_red]Exception[/] in get_event_identifier [dark_orange4]{e.__class__.__name__}[/]")
+            # print(f"[bright_red]Exception[/] in get_event_identifier [dark_orange4]{e.__class__.__name__}[/]")
             raise typer.Exit(1)

{centralcli-4.0.2 → centralcli-4.2.0}/centralcli/central.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import base64
 import json
 import time
+import tablib
+import yaml
 from asyncio.proactor_events import _ProactorBasePipeTransport
 from datetime import datetime, timedelta
 from enum import Enum
@@ -1042,7 +1044,7 @@ class CentralApi(Session):
 
     # TODO cleanup the way raw is combined, see show wids all.
     # TODO add full kwargs and type-hints
-    async def get_all_devicesv2(self, **kwargs) -> Response:
+    async def get_all_devicesv2(self, calculate_client_count: bool = True, **kwargs) -> Response:
         """Get all devices from Aruba Central
 
         Returns:
@@ -1058,7 +1060,7 @@ class CentralApi(Session):
         }
         _output = {}
 
-        reqs = [self.BatchRequest(self.get_devices, dev_type, **kwargs) for dev_type in dev_types]
+        reqs = [self.BatchRequest(self.get_devices, dev_type, calculate_client_count=calculate_client_count, **kwargs) for dev_type in dev_types]
         res = await self._batch_request(reqs)
         _failure_idxs = [idx for idx, r in enumerate(res) if not r]
         if _failure_idxs:
@@ -1075,7 +1077,7 @@ class CentralApi(Session):
 
         resp = res[-1]
         # TODO pass raw JSON use pydantic models in cleaner for non-verbose, verbose, --clients --stats outputs
-        if kwargs.get("calculate_client_count"):
+        if calculate_client_count:
             _output = {k: [{"client_count": inner.get("client_count", "-"), **inner} for inner in utils.listify(v)] for k, v in zip(dev_types, [r.output for r in res]) if v}
         else:
             _output = {k: utils.listify(v) for k, v in zip(dev_types, [r.output for r in res]) if v}
@@ -1105,7 +1107,9 @@ class CentralApi(Session):
 
         return resp
 
-    # API-FLAW aos-sw always shows VLAN as 1 (allowed_vlans represents the PVID for access)
+    # API-FLAW aos-sw always shows VLAN as 1 (allowed_vlans represents the PVID for an access port, include all VLANs on a trunk port, no indication of native)
+    # API-FLAW aos-sw always shows mode as access, cx does as well, but has vlan_mode which is accurate
+    # API-FLAW neither show interface name/description
     async def get_switch_ports(self, serial: str, slot: str = None, aos_sw: bool = False) -> Response:
         """Switch Ports Details.
 
@@ -1113,7 +1117,7 @@ class CentralApi(Session):
             serial (str): Serial number of switch to be queried
             slot (str, optional): Slot name of the ports to be queried {For chassis type switches
                 only}.
-            aos_sw (bool, optional): Device is ArubaOS-Switch. Defaults to False
+            aos_sw (bool, optional): Device is ArubaOS-Switch. Defaults to False (indicating CX switch)
 
         Returns:
             Response: CentralAPI Response object
@@ -1322,7 +1326,7 @@ class CentralApi(Session):
         show_resource_details: bool = False,
         cluster_id: str = None,
         model: str = None,
-        calculate_client_count: bool = False,
+        calculate_client_count: bool = True,
         calculate_ssid_count: bool = False,
         macaddr: str = None,
         public_ip_address: str = None,
@@ -1558,20 +1562,9 @@ class CentralApi(Session):
 
         return await self.get(url)
 
-    # DELME not used should be safe to remove after verification
-    async def get_gateways_by_group(self, group):
-        url = "/monitoring/v1/mobility_controllers" if config.is_cop else "/monitoring/v1/gateways"
-        params = {"group": group}
-        return await self.get(url, params=params)
-
     async def get_group_for_dev_by_serial(self, serial_num):
         return await self.get(f"/configuration/v1/devices/{serial_num}/group")
 
-    # async def get_dhcp_client_info_by_gw(self, serial_num):
-    #     url = f"/monitoring/v1/mobility_controllers/{serial_num}/dhcp_clients"
-    #     params = {"reservation": False}
-    #     return await self.get(url, params=params)
-
     async def get_vlan_info_by_gw(self, serial_num):
         return await self.get(f"/monitoring/v1/mobility_controllers/{serial_num}/vlan")
 
@@ -1584,11 +1577,6 @@ class CentralApi(Session):
         url = f"/monitoring/v1/mobility_controllers/{serial_num}/uplinks/tunnel_stats"
         return await self.get(url)
 
-    async def get_uplink_state_by_group(self, group: str) -> Response:
-        url = "/monitoring/v1/mobility_controllers/uplinks/distribution"
-        params = {"group": group}
-        return await self.get(url, params)
-
     # TODO move cleaner
     async def get_all_sites(
         self,
@@ -1626,12 +1614,15 @@ class CentralApi(Session):
         event_description: str = None,
         event_type: str = None,
         fields: str = None,
-        calculate_total: bool = None,
+        calculate_total: bool = True,
         offset: int = 0,
         limit: int = 1000,
     ) -> Response:
         """List Events. v2
 
+        Endpoint allows a max of 10000 records to be retrieved.  The sum of offset + limit can not
+        exceed 10,000
+
         Args:
             group (str, optional): Filter by group name
             swarm_id (str, optional): Filter by Swarm ID
@@ -1655,7 +1646,7 @@ class CentralApi(Session):
             event_type (str, optional): Filter by event type
             fields (str, optional): Comma separated list of fields to be returned. Valid fields are
                 number, level
-            calculate_total (bool, optional): Whether to calculate total events
+            calculate_total (bool, optional): Whether to calculate total events. Defaults to True.
             offset (int, optional): Pagination offset Defaults to 0.
             limit (int, optional): Pagination limit. Default is 100 and max is 1000 Defaults to 1000.
 
@@ -1668,8 +1659,8 @@ class CentralApi(Session):
             "group": group,
             "swarm_id": swarm_id,
             "label": label,
-            "from_tinmestamp": from_ts,
-            "to_tinmestamp": to_ts,
+            "from_timestamp": from_ts,
+            "to_timestamp": to_ts,
             'macaddr': macaddr,
             'bssid': bssid,
             'device_mac': device_mac,
@@ -1682,7 +1673,7 @@ class CentralApi(Session):
             'event_description': event_description,
             'event_type': event_type,
             'fields': fields,
-            'calculate_total': calculate_total,
+            'calculate_total': str(calculate_total),
             "offset": offset,
             "limit": limit,
         }
@@ -1902,29 +1893,6 @@ class CentralApi(Session):
         else:
             return Response(error="Missing Required Parameters")
 
-    async def update_ssh_creds(self, device_serial: str, username: str, password: str) -> Response:
-        """Set Username, password required for establishing SSH connection to switch.
-
-        This method only applies to switches
-
-        Args:
-            device_serial (str): Serial number of the switch.
-            username (str): SSH username
-            password (str): SSH password
-
-        Returns:
-            Response: CentralAPI Response object
-            Successful Response body (Response.output): "Success"
-        """
-        url = f"/configuration/v1/devices/{device_serial}/ssh_connection"
-
-        json_data = {
-            'username': username,
-            'password': password
-        }
-
-        return await self.post(url, json_data=json_data)
-
     async def get_task_status(
         self,
         task_id: str,
@@ -2021,24 +1989,6 @@ class CentralApi(Session):
 
         return await self.get(url)
 
-    async def get_controller_vlans(self, serial: str) -> Response:
-        """Get Mobility Controllers VLAN details.
-
-        Args:
-            serial (str): Serial number of mobility controller to be queried
-
-        Returns:
-            Response: CentralAPI Response object
-        """
-        url = f"/monitoring/v1/mobility_controllers/{serial}/vlan"
-
-        return await self.get(url)
-
-    # async def get_ts_commands(self, dev_type: Literal['iap', 'mas', 'switch', 'controller']) -> Response:
-    #     url = "/troubleshooting/v1/commands"
-    #     params = {"device_type": dev_type}
-    #     return await self.get(url, params=params)
-
     async def get_ts_commands(
         self,
         device_type: Literal['iap', 'mas', 'switch', 'controller', 'cx'],
@@ -2196,6 +2146,56 @@ class CentralApi(Session):
 
         return await self.get(url)
 
+    async def get_switch_neighbors_v1(
+        self,
+        serial: str,
+    ) -> Response:
+        """Get lldp device neighbor info for CX switch.
+
+        If used on AOS-SW will only return neighbors that are CX switches
+
+        Args:
+            serial (str): id of the switch
+
+        Returns:
+            Response: CentralAPI Response object
+        """
+        url = f"/monitoring/v1/cx_switches/{serial}/neighbors"
+
+        return await self.get(url)
+
+    async def get_cx_switch_stack_neighbors_v1(
+        self,
+        stack_id: str,
+    ) -> Response:
+        """Get lldp device neighbor info for CX switch stack.
+
+        Args:
+            stack_id (str): Filter by stack_id
+
+        Returns:
+            Response: CentralAPI Response object
+        """
+        url = f"/monitoring/v1/cx_switch_stacks/{stack_id}/neighbors"
+
+        return await self.get(url)
+
+    async def get_switch_vsx_detail(
+        self,
+        serial: str,
+    ) -> Response:
+        """Get switch vsx info for CX switch.
+
+        Args:
+            serial (str): Filter by switch serial
+
+        Returns:
+            Response: CentralAPI Response object
+        """
+        url = f"/monitoring/v1/cx_switches/{serial}/vsx"
+
+        return await self.get(url)
+
     async def do_multi_group_snapshot(
         self,
         backup_name: str,
@@ -3159,7 +3159,7 @@ class CentralApi(Session):
         self,
         swarm_id: str,
         command: Literal[
-            "reboot_swarm",
+            "reboot",
             "erase_configuration",
         ]
     ) -> Response:
@@ -3168,11 +3168,14 @@ class CentralApi(Session):
         Args:
             swarm_id (str): Swarm ID of device
             command (str): Command mentioned in the description that is to be executed
-                valid: 'reboot_swarm', 'erase_configuration'
+                valid: 'reboot', 'erase_configuration'
 
         Returns:
             Response: CentralAPI Response object
         """
+        if command == "reboot":
+            command = "reboot_swarm"
+
         url = f"/device_management/v1/swarm/{swarm_id}/action/{command}"
 
         return await self.post(url)
@@ -4146,29 +4149,6 @@ class CentralApi(Session):
 
         return await self.delete(url)
 
-    # TODO may remove this would show the device in the group, but didn't behave as expected (device was not in device list)
-    async def assign_devices_to_group(self,  group: str, serial_nums: Union[List[str], str]) -> Response:
-        """Assign devices to pre-provisioned group.
-
-        // Used indirectly by add device (when group option provided) //
-
-        Args:
-            group (str): Group name
-            serials (List[str]|str): Device serial number or list of device serial numbers.
-
-        Returns:
-            Response: CentralAPI Response object
-        """
-        url = "/device_management/v1/group/assign"
-        serial_nums = utils.listify(serial_nums)
-
-        json_data = {
-            'serials': serial_nums,
-            'group': group
-        }
-
-        return await self.post(url, json_data=json_data)
-
     async def preprovision_device_to_group(
         self,
         group_name: str,
@@ -5634,6 +5614,44 @@ class CentralApi(Session):
         url = "/keymgmt/v1/health"
         return await self.get(url)
 
+    async def cloudauth_get_registered_macs(
+        self,
+        search: str = None,
+        sort: str = None,
+        filename: str = None,
+    ) -> Response:
+        """Fetch all Mac Registrations as a CSV file.
+
+        Args:
+            search (str, optional): Filter the Mac Registrations by Mac Address and Client Name.
+                Does a 'contains' match.
+            sort (str, optional): Sort order  Valid Values: +name, -name, +display_name,
+                -display_name
+            filename (str, optional): Suggest a file name for the downloading file via content
+                disposition header.
+
+        Returns:
+            Response: CentralAPI Response object
+        """
+        url = "/cloudauth/api/v3/bulk/mac"
+
+        params = {
+            'search': search,
+            'sort': sort,
+            'filename': filename
+        }
+
+        resp = await self.get(url, params=params)
+
+        if resp:
+            try:
+                ds = tablib.Dataset().load(resp.output)
+                resp.output = yaml.load(ds.json, Loader=yaml.SafeLoader)
+            except Exception as e:
+                log.error(f"cloudauth_get_registered_macs caught {e.__class__.__name__} trying to convert csv return from API to dict.", caption=True)
+
+        return resp
+
     async def get_user_accounts(
         self,
         app_name: str = None,
@@ -5672,7 +5690,10 @@ class CentralApi(Session):
             'limit': limit
         }
 
-        return await self.get(url, params=params)
+        # TODO this needs a fair amount of massaging to turn into a command, it's nested dicts
+        # example response in private vscode dir.
+        resp = await self.get(url, params=params)
+        return resp
 
 if __name__ == "__main__":
     pass