isemass 0.1.0__tar.gz

isemass-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: isemass
+Version: 0.1.0
+Summary: CLI framework for mass Cisco ISE related operations.
+License-Expression: Apache-2.0
+Requires-Dist: click>=8.1
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: requests>=2.32
+Requires-Dist: rich>=13.7
+Requires-Dist: urllib3>=2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# isemass
+
+`isemass` is a Python CLI for mass operations related to Cisco ISE.
+
+The `coa` command performs Cisco ISE API Change-of-Authorization requests from MAC addresses
+found in an input text file. The `swauth` command is still a placeholder for future switch SSH
+reauthentication work.
+
+## Development
+
+```bash
+uv sync
+uv run isemass --help
+uv run pytest
+uv run ruff check .
+```
+
+## Commands
+
+```bash
+isemass init
+isemass coa --input-file macs.txt --host ise-mnt.example.com --node ise-psn01
+isemass coa --input-file macs.txt --host ise-mnt.example.com --node ise-psn01 --yes
+isemass swauth
+```
+
+`isemass init` creates `settings.toml` in the operating system's standard user config directory
+for the `isemass` app. 
+
+`isemass coa` accepts colon, dash, and Cisco dotted MAC formats, normalizes them to uppercase
+colon format, removes duplicates, prompts for the API password, previews the target MAC list, and
+asks for confirmation before sending requests. Use `--insecure` or `insecure = true` only when you
+need to skip HTTPS certificate validation.
+
+## Input Config
+
+Priority of configuration input is this order:
+1. CLI arguments
+2. settings.toml values
+3. back-end defaults (in defaults.py)

isemass-0.1.0/README.md

@@ -0,0 +1,40 @@
+# isemass
+
+`isemass` is a Python CLI for mass operations related to Cisco ISE.
+
+The `coa` command performs Cisco ISE API Change-of-Authorization requests from MAC addresses
+found in an input text file. The `swauth` command is still a placeholder for future switch SSH
+reauthentication work.
+
+## Development
+
+```bash
+uv sync
+uv run isemass --help
+uv run pytest
+uv run ruff check .
+```
+
+## Commands
+
+```bash
+isemass init
+isemass coa --input-file macs.txt --host ise-mnt.example.com --node ise-psn01
+isemass coa --input-file macs.txt --host ise-mnt.example.com --node ise-psn01 --yes
+isemass swauth
+```
+
+`isemass init` creates `settings.toml` in the operating system's standard user config directory
+for the `isemass` app. 
+
+`isemass coa` accepts colon, dash, and Cisco dotted MAC formats, normalizes them to uppercase
+colon format, removes duplicates, prompts for the API password, previews the target MAC list, and
+asks for confirmation before sending requests. Use `--insecure` or `insecure = true` only when you
+need to skip HTTPS certificate validation.
+
+## Input Config
+
+Priority of configuration input is this order:
+1. CLI arguments
+2. settings.toml values
+3. back-end defaults (in defaults.py)

isemass-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "isemass"
+version = "0.1.0"
+description = "CLI framework for mass Cisco ISE related operations."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = [
+    "click>=8.1",
+    "platformdirs>=4.2",
+    "requests>=2.32",
+    "rich>=13.7",
+    "urllib3>=2.0",
+]
+
+[project.scripts]
+isemass = "isemass.cli:cli"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/isemass"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"

isemass-0.1.0/src/isemass/__init__.py

@@ -0,0 +1,4 @@
+"""isemass CLI package."""
+
+__version__ = "0.1.0"
+

isemass-0.1.0/src/isemass/cli.py

@@ -0,0 +1,231 @@
+"""Click command line interface for isemass."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.table import Table
+
+from isemass import __version__
+from isemass import coa as coa_ops
+from isemass.config import SettingsError, get_settings_path, load_settings, write_default_settings
+from isemass.console import console
+
+
+def _load_settings_for_cli() -> dict[str, dict[str, Any]]:
+    try:
+        return load_settings()
+    except SettingsError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _section(settings: dict[str, dict[str, Any]], name: str) -> dict[str, Any]:
+    values = settings.get(name, {})
+    if not isinstance(values, dict):
+        raise click.ClickException(f"Invalid settings: [{name}] must be a table.")
+    return values
+
+
+def _resolve_option(cli_value: Any, config_value: Any) -> Any:
+    return cli_value if cli_value is not None else config_value
+
+
+def _missing_required_options(options: dict[str, Any]) -> list[str]:
+    return [option_name for option_name, value in options.items() if value in (None, "")]
+
+
+def _coerce_input_file(value: Any) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_file():
+        raise click.ClickException(f"Input file does not exist: {path}")
+    return path
+
+
+def _coerce_positive_int(value: Any, *, field_name: str) -> int:
+    try:
+        resolved = int(value)
+    except (TypeError, ValueError) as exc:
+        raise click.ClickException(f"{field_name} must be a positive integer.") from exc
+
+    if resolved < 1:
+        raise click.ClickException(f"{field_name} must be a positive integer.")
+
+    return resolved
+
+
+def _coerce_bool(value: Any, *, field_name: str) -> bool:
+    if isinstance(value, bool):
+        return value
+
+    raise click.ClickException(f"{field_name} must be a boolean true or false.")
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="isemass")
+def cli() -> None:
+    """Mass Cisco ISE related operations."""
+
+
+@cli.command()
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite an existing settings.toml file.",
+)
+def init(force: bool) -> None:
+    """Create the optional settings.toml file."""
+    path, wrote_file = write_default_settings(force=force)
+
+    if not wrote_file:
+        raise click.ClickException(f"Settings file already exists: {path}. Use --force to overwrite.")
+
+    console.print(f"[green]Created settings file:[/green] '{path}'")
+
+
+@cli.command()
+@click.option(
+    "-i",
+    "--input-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Input text file containing MAC addresses.",
+)
+@click.option(
+    "-u",
+    "--username",
+    help="API username. Prompts if omitted and not configured.",
+)
+@click.option(
+    "-w",
+    "--max-workers",
+    type=int,
+    help="Max workers for multitasking at once.",
+)
+@click.option(
+    "--host",
+    help="FQDN or IP for the API request, typically the MnT node.",
+)
+@click.option(
+    "-n",
+    "--node",
+    help="Short ISE node name that processes the CoA request.",
+)
+@click.option(
+    "-k",
+    "--insecure",
+    is_flag=True,
+    default=None,
+    help="Skip HTTPS certificate validation.",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Skip confirmation before submitting CoA requests.",
+)
+def coa(
+    input_file: Path | None,
+    username: str | None,
+    max_workers: int | None,
+    host: str | None,
+    node: str | None,
+    insecure: bool | None,
+    yes: bool,
+) -> None:
+    """ISE Mass CoA through API."""
+    settings = _load_settings_for_cli()
+    coa_settings = _section(settings, "coa")
+
+    required_values = {
+        "--input-file": _resolve_option(input_file, coa_settings.get("input_file")),
+        "--host": _resolve_option(host, coa_settings.get("host")),
+        "--node": _resolve_option(node, coa_settings.get("node")),
+    }
+    missing = _missing_required_options(required_values)
+    if missing:
+        missing_options = ", ".join(missing)
+        raise click.UsageError(
+            f"Missing required option(s): {missing_options}. "
+            "Provide them on the CLI or in [coa]."
+        )
+
+    resolved_input_file = _coerce_input_file(required_values["--input-file"])
+    resolved_host = str(required_values["--host"])
+    resolved_node = str(required_values["--node"])
+    resolved_username = _resolve_option(username, coa_settings.get("username"))
+    if not resolved_username:
+        resolved_username = click.prompt("API username", type=str)
+
+    resolved_max_workers = _coerce_positive_int(
+        _resolve_option(max_workers, coa_settings.get("max_workers")),
+        field_name="max_workers",
+    )
+    resolved_insecure = _coerce_bool(
+        _resolve_option(insecure, coa_settings.get("insecure")),
+        field_name="insecure",
+    )
+
+    password = click.prompt(f"API password for {resolved_username}", hide_input=True, type=str)
+    macs = coa_ops.extract_macs_from_file(resolved_input_file)
+    if not macs:
+        raise click.ClickException(f"No MAC addresses found in {resolved_input_file}.")
+
+    _print_mac_preview(macs)
+    if not yes and not click.confirm("Continue with CoA operation?", default=False):
+        raise click.ClickException("Operation not approved. Aborting.")
+
+    console.print(f"Starting CoA requests for {len(macs)} MAC address(es)...", highlight=False)
+    for result in coa_ops.run_coa_requests(
+        macs=macs,
+        host=resolved_host,
+        node=resolved_node,
+        username=str(resolved_username),
+        password=password,
+        max_workers=resolved_max_workers,
+        insecure=resolved_insecure,
+    ):
+        _print_coa_result(result)
+
+
+@cli.command()
+def swauth() -> None:
+    """Mass session reauthentication through switch SSH."""
+    settings = _load_settings_for_cli()
+    swauth_settings = _section(settings, "swauth")
+    verbose = _coerce_bool(swauth_settings.get("verbose", False), field_name="verbose")
+
+    console.print("[yellow]Switch reauthentication is not implemented yet.[/yellow]")
+    console.print(f"Verbose: {verbose}")
+    console.print(f"Settings path: {get_settings_path()}")
+
+
+def _print_mac_preview(macs: list[str]) -> None:
+    table = Table(title=f"Unique MAC addresses ({len(macs)})")
+    table.add_column("#", justify="right")
+    table.add_column("MAC address", style="cyan")
+
+    for index, mac in enumerate(macs, start=1):
+        table.add_row(str(index), mac)
+
+    console.print(table)
+
+
+def _print_coa_result(result: coa_ops.CoaResult) -> None:
+    styles = {
+        coa_ops.CoaStatus.SUCCEEDED: "green",
+        coa_ops.CoaStatus.COA_FAILED: "yellow",
+        coa_ops.CoaStatus.REQUEST_FAILED: "red",
+    }
+    labels = {
+        coa_ops.CoaStatus.SUCCEEDED: "SUCCEEDED",
+        coa_ops.CoaStatus.COA_FAILED: "FAILED/UNDETERMINED",
+        coa_ops.CoaStatus.REQUEST_FAILED: "REQUEST FAILED",
+    }
+    style = styles[result.status]
+    label = labels[result.status]
+
+    console.print(
+        f"{result.mac} | {result.seconds:>5.2f}s | [{style}]{label}[/{style}] | {result.detail}",
+        highlight=False,
+    )

isemass-0.1.0/src/isemass/coa.py

@@ -0,0 +1,225 @@
+"""Cisco ISE CoA API helpers."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from time import perf_counter
+import re
+from typing import Any, Callable, Iterable
+from xml.etree import ElementTree
+
+import requests
+import urllib3
+
+HEADERS = {
+    "Accept": "application/xml",
+}
+REQUEST_TIMEOUT_SECONDS = 30
+
+# REGEX for all formats of MAC address.
+# "?:" removes groups so re.findall returns complete MAC address strings.
+RE_MAC_COLON = r"(?:[0-9A-Fa-f]{2}:){5}(?:[0-9A-Fa-f]{2})"
+RE_MAC_DASH = r"(?:[0-9A-Fa-f]{2}-){5}(?:[0-9A-Fa-f]{2})"
+RE_MAC_CISCO = r"(?:[0-9A-Fa-f]{4}\.){2}(?:[0-9A-Fa-f]{4})"
+RE_MAC_ALL = RE_MAC_COLON + r"|" + RE_MAC_DASH + r"|" + RE_MAC_CISCO
+RE_MAC_PATTERN = re.compile(RE_MAC_ALL)
+
+
+class CoaStatus(StrEnum):
+    """Normalized CoA request outcome."""
+
+    REQUEST_FAILED = "request_failed"
+    COA_FAILED = "coa_failed"
+    SUCCEEDED = "succeeded"
+
+
+@dataclass(frozen=True)
+class CoaResult:
+    """Result for one MAC address CoA request."""
+
+    mac: str
+    status: CoaStatus
+    seconds: float
+    detail: str
+
+
+RequestFunc = Callable[..., Any]
+
+
+def normalize_mac(mac: str) -> str:
+    """Normalize a supported MAC address string to uppercase colon format."""
+    compact = mac.replace(":", "").replace("-", "").replace(".", "").upper()
+    return ":".join(compact[index : index + 2] for index in range(0, len(compact), 2))
+
+
+def extract_macs(text: str) -> list[str]:
+    """Extract unique MAC addresses from text while preserving first-seen order."""
+    unique_macs: list[str] = []
+    seen: set[str] = set()
+
+    for match in RE_MAC_PATTERN.findall(text):
+        normalized = normalize_mac(match)
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        unique_macs.append(normalized)
+
+    return unique_macs
+
+
+def extract_macs_from_file(path: Path) -> list[str]:
+    """Read text from path and extract unique MAC addresses."""
+    return extract_macs(path.read_text(encoding="utf-8"))
+
+
+def build_coa_url(*, host: str, node: str, mac: str) -> str:
+    """Build the Cisco ISE CoA Reauth API URL."""
+    return f"https://{host}/admin/API/mnt/CoA/Reauth/{node}/{mac}/0"
+
+
+def perform_coa_request(
+    *,
+    mac: str,
+    host: str,
+    node: str,
+    username: str,
+    password: str,
+    verify_tls: bool,
+    timeout: float = REQUEST_TIMEOUT_SECONDS,
+    request_func: RequestFunc = requests.get,
+) -> CoaResult:
+    """Perform one Cisco ISE CoA request and classify the result."""
+    url = build_coa_url(host=host, node=node, mac=mac)
+    start = perf_counter()
+
+    try:
+        response = request_func(
+            url,
+            headers=HEADERS,
+            verify=verify_tls,
+            auth=(username, password),
+            timeout=timeout,
+        )
+    except requests.RequestException as exc:
+        return CoaResult(
+            mac=mac,
+            status=CoaStatus.REQUEST_FAILED,
+            seconds=_elapsed_seconds(start),
+            detail=f"API request failed: {exc}",
+        )
+    
+    # TEMP TESTING. MIGHT BE USED FOR VERBOSITY LATER
+    # print(response.status_code, response.headers, response.text)
+
+    seconds = _elapsed_seconds(start)
+    status_code = getattr(response, "status_code", None)
+    if status_code is None or not 200 <= status_code < 300:
+        reason = getattr(response, "reason", "")
+        reason_text = f" {reason}" if reason else ""
+        return CoaResult(
+            mac=mac,
+            status=CoaStatus.REQUEST_FAILED,
+            seconds=seconds,
+            detail=f"HTTP {status_code}{reason_text}",
+        )
+
+    result_value = _extract_remote_coa_result(getattr(response, "text", ""))
+    if result_value is None:
+        return CoaResult(
+            mac=mac,
+            status=CoaStatus.COA_FAILED,
+            seconds=seconds,
+            detail="ISE response did not include remoteCoA.results",
+        )
+
+    if result_value.casefold() == "true":
+        return CoaResult(
+            mac=mac,
+            status=CoaStatus.SUCCEEDED,
+            seconds=seconds,
+            detail="ISE remoteCoA.results=true",
+        )
+
+    return CoaResult(
+        mac=mac,
+        status=CoaStatus.COA_FAILED,
+        seconds=seconds,
+        detail=f"ISE remoteCoA.results={result_value}",
+    )
+
+
+def run_coa_requests(
+    *,
+    macs: Iterable[str],
+    host: str,
+    node: str,
+    username: str,
+    password: str,
+    max_workers: int,
+    insecure: bool,
+) -> Iterable[CoaResult]:
+    """Run CoA requests concurrently and yield results as they complete."""
+    verify_tls = not insecure
+    if insecure:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        future_to_mac = {
+            executor.submit(
+                perform_coa_request,
+                mac=mac,
+                host=host,
+                node=node,
+                username=username,
+                password=password,
+                verify_tls=verify_tls,
+            ): mac
+            for mac in macs
+        }
+
+        for future in as_completed(future_to_mac):
+            mac = future_to_mac[future]
+            try:
+                yield future.result()
+            except Exception as exc:
+                yield CoaResult(
+                    mac=mac,
+                    status=CoaStatus.REQUEST_FAILED,
+                    seconds=0.0,
+                    detail=f"Unexpected worker error: {exc}",
+                )
+
+
+def _elapsed_seconds(start: float) -> float:
+    return round(perf_counter() - start, 2)
+
+
+def _extract_remote_coa_result(xml_text: str) -> str | None:
+    try:
+        root = ElementTree.fromstring(xml_text)
+    except ElementTree.ParseError:
+        return None
+
+    remote_coa = _find_first_element(root, "remoteCoA")
+    if remote_coa is None:
+        return None
+
+    results = _find_first_element(remote_coa, "results")
+    if results is None or results.text is None:
+        return None
+
+    return results.text.strip()
+
+
+def _find_first_element(root: ElementTree.Element, local_name: str) -> ElementTree.Element | None:
+    for element in root.iter():
+        if _local_name(element.tag) == local_name:
+            return element
+    return None
+
+
+def _local_name(tag: str) -> str:
+    return tag.rsplit("}", maxsplit=1)[-1]

isemass-0.1.0/src/isemass/config.py

@@ -0,0 +1,81 @@
+"""Optional settings.toml support for isemass."""
+
+from __future__ import annotations
+
+import copy
+import tomllib
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+from isemass.defaults import DEFAULT_SETTINGS
+
+APP_NAME = "isemass"
+SETTINGS_FILENAME = "settings.toml"
+TEMPLATE_PACKAGE = "isemass.templates"
+
+
+class SettingsError(Exception):
+    """Raised when settings.toml cannot be loaded safely."""
+
+
+def get_config_dir() -> Path:
+    """Return the platform-specific user config directory."""
+    return Path(user_config_dir(APP_NAME))
+
+
+def get_settings_path() -> Path:
+    """Return the platform-specific settings.toml path."""
+    return get_config_dir() / SETTINGS_FILENAME
+
+
+def default_settings() -> dict[str, dict[str, Any]]:
+    """Return a copy of the built-in settings defaults."""
+    return copy.deepcopy(DEFAULT_SETTINGS)
+
+
+def load_settings() -> dict[str, dict[str, Any]]:
+    """Load settings.toml and merge it over built-in defaults."""
+    path = get_settings_path()
+    settings = default_settings()
+
+    if not path.exists():
+        return settings
+
+    try:
+        parsed = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SettingsError(f"Invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise SettingsError(f"Unable to read settings file {path}: {exc}") from exc
+
+    for section_name, section_values in parsed.items():
+        if not isinstance(section_values, dict):
+            raise SettingsError(
+                f"Invalid settings in {path}: top-level key '{section_name}' must be a table."
+            )
+        settings.setdefault(section_name, {}).update(section_values)
+
+    return settings
+
+
+def load_settings_template() -> str:
+    """Return the packaged default settings.toml template."""
+    return files(TEMPLATE_PACKAGE).joinpath(SETTINGS_FILENAME).read_text(encoding="utf-8")
+
+
+def write_default_settings(*, force: bool = False) -> tuple[Path, bool]:
+    """Write the default settings template.
+
+    Returns the settings path and a boolean indicating whether a file was written.
+    """
+    path = get_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if path.exists() and not force:
+        return path, False
+
+    path.write_text(load_settings_template(), encoding="utf-8")
+    return path, True

isemass-0.1.0/src/isemass/console.py

@@ -0,0 +1,6 @@
+"""Shared Rich console."""
+
+from rich.console import Console
+
+console = Console()
+

isemass-0.1.0/src/isemass/defaults.py

@@ -0,0 +1,16 @@
+"""Built-in settings defaults."""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_SETTINGS: dict[str, dict[str, Any]] = {
+    "coa": {
+        "verbose": False,
+        "max_workers": 20,
+        "insecure": False,
+    },
+    "swauth": {
+        "verbose": False,
+    },
+}

isemass-0.1.0/src/isemass/templates/__init__.py

@@ -0,0 +1,2 @@
+"""Packaged templates for isemass."""
+

isemass-0.1.0/src/isemass/templates/settings.toml

@@ -0,0 +1,25 @@
+[coa]
+# Turns on extra verbose logging for CoA operations.
+verbose = false
+
+# Optional API username. Passwords/tokens are intentionally not stored here.
+# username = "bob-example"
+
+# Input text file containing MAC addresses. CLI equivalent: -i/--input-file.
+# input_file = "macs.txt"
+
+# API host to connect to, typically the MnT node FQDN or IP.
+# host = "ise-mnt.example.com"
+
+# Short ISE node name that processes the CoA request, typically a PSN.
+# node = "ise-psn01"
+
+# Maximum number of concurrent workers for CoA tasks.
+max_workers = 20
+
+# Skip HTTPS certificate validation when set to true.
+insecure = false
+
+[swauth]
+# Turns on extra verbose logging for switch reauthentication operations.
+verbose = false