nac-analytics 0.1.0__py3-none-any.whl

nac_analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Change analysis for Cisco Nexus Dashboard 4.2.1+."""
+
+from importlib.metadata import version
+
+__version__ = version(__name__)

nac_analytics/__main__.py

@@ -0,0 +1,4 @@
+from nac_analytics.cli import main
+
+if __name__ == "__main__":
+    main()

nac_analytics/cli.py

@@ -0,0 +1,103 @@
+"""Root command line interface.
+
+`nac-analytics` is organised as `nac-analytics <product> <verb>`: each Cisco
+product is a command group (see ``nac_analytics.products``), plus global
+commands like ``version``. This module mounts the registered product groups and
+routes pre-Typer configuration loading to the selected product.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from dotenv import find_dotenv, load_dotenv
+
+from nac_analytics import __version__
+from nac_analytics.core.cli_args import strip_config_option
+from nac_analytics.core.exceptions import InputError
+from nac_analytics.core.product import Product
+from nac_analytics.products import REGISTRY, resolve_product
+
+ROOT_HELP = """\
+Change analytics for Cisco products.
+
+Run a product group followed by a command, for example:
+
+  nac-analytics nexus-dashboard doctor      (alias: nd)
+
+Each product carries its own commands and configuration; see
+`nac-analytics <product> --help`. Products available today are listed below;
+more Cisco products are planned."""
+
+app = typer.Typer(
+    help=ROOT_HELP,
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+# Mount every registered product as `nac-analytics <cli_name> ...`, with any
+# short aliases hidden from the help so the surface stays uncluttered.
+for _product in REGISTRY:
+    app.add_typer(_product.app, name=_product.cli_name)
+    for _alias in _product.aliases:
+        app.add_typer(_product.app, name=_alias, hidden=True)
+
+
+@app.command()
+def version() -> None:
+    """Print the version and exit."""
+    typer.echo(f"nac-analytics {__version__}")
+
+
+def _active_product(args: list[str]) -> Product | None:
+    """Return the product the invocation selects, ignoring a leading --config."""
+    _, rest = strip_config_option(args)
+    for token in rest:
+        if token.startswith("-"):
+            return None
+        return resolve_product(token)
+    return None
+
+
+def _wants_help(args: list[str]) -> bool:
+    """Return True when the invocation only resolves or prints help.
+
+    Config must not be loaded or validated in this case. ``--help`` is an
+    eager Click option that short-circuits (printing help and exiting) before
+    any command runs, so loading config first would let an invalid or
+    flat/unscoped ``nac-analytics.yaml`` break a plain ``--help``. A product
+    group invoked with no verb likewise falls back to printing its group help
+    (``no_args_is_help``), so a bare product token counts as a help request
+    too. Real command execution always carries a verb and no help flag, and
+    still triggers the strict config bootstrap below.
+    """
+    _, rest = strip_config_option(args)
+    if "--help" in rest or "-h" in rest:
+        return True
+    non_flags = [token for token in rest if not token.startswith("-")]
+    return len(non_flags) == 1 and resolve_product(non_flags[0]) is not None
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    product = _active_product(args)
+    load_config = (
+        product is not None and product.bootstrap is not None and not _wants_help(args)
+    )
+    try:
+        if load_config:
+            assert product is not None and product.bootstrap is not None
+            remaining = product.bootstrap(args)
+        else:
+            _, remaining = strip_config_option(args)
+    except InputError as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise SystemExit(InputError.exit_code) from exc
+    sys.argv = [sys.argv[0], *remaining]
+    # `.env` is read after YAML so a real environment variable or CLI flag still
+    # wins. Values already in `os.environ` are left untouched.
+    load_dotenv(find_dotenv(usecwd=True))
+    if product is not None and product.apply_legacy_env is not None:
+        product.apply_legacy_env()
+    app()

nac_analytics/core/__init__.py

@@ -0,0 +1,5 @@
+"""Product-agnostic building blocks shared by every product package.
+
+Nothing in ``core`` may import from ``nac_analytics.products``; the dependency
+only ever points the other way (products build on core).
+"""

nac_analytics/core/cli_args.py

@@ -0,0 +1,32 @@
+"""Pre-Typer argv handling shared across products.
+
+``--config`` is resolved before Typer runs (it selects the YAML file that seeds
+the environment), so it is stripped from argv here rather than declared as a
+Typer option.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+CONFIG_OPTION = "--config"
+
+
+def strip_config_option(argv: list[str]) -> tuple[Path | None, list[str]]:
+    """Remove a root-level ``--config`` option from ``argv`` before Typer runs."""
+    remaining: list[str] = []
+    config_path: Path | None = None
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
+        if arg == CONFIG_OPTION and index + 1 < len(argv):
+            config_path = Path(argv[index + 1])
+            index += 2
+            continue
+        if arg.startswith(f"{CONFIG_OPTION}="):
+            config_path = Path(arg.split("=", 1)[1])
+            index += 1
+            continue
+        remaining.append(arg)
+        index += 1
+    return config_path, remaining

nac_analytics/core/config.py

@@ -0,0 +1,72 @@
+"""Connection settings, sourced from CLI options with `.env` behind them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from nac_analytics.core.exceptions import InputError
+
+# The login endpoint rejects a missing or empty `domain` with HTTP 500, so
+# there is always a value here.
+DEFAULT_DOMAIN = "DefaultAuth"
+
+
+def normalise_host(host: str) -> str:
+    """Strip any URL scheme and trailing slashes from a host.
+
+    A host carrying its own scheme would produce `https://https://...`.
+    """
+    return host_scheme(host)[1]
+
+
+def host_scheme(host: str) -> tuple[str, str]:
+    """Return ``(scheme, host)`` where scheme is ``https`` or ``http``."""
+    value = host.strip()
+    lowered = value.lower()
+    for prefix, scheme in (("https://", "https"), ("http://", "http")):
+        if lowered.startswith(prefix):
+            return scheme, value[len(prefix) :].rstrip("/")
+    return "https", value.rstrip("/")
+
+
+@dataclass
+class Config:
+    """Everything needed to reach one Nexus Dashboard."""
+
+    host: str
+    username: str
+    # Kept out of the generated __repr__, which reaches debuggers, log lines
+    # and exception renderings.
+    password: str = field(repr=False)
+    domain: str = DEFAULT_DOMAIN
+    fabric: str = ""
+    verify_ssl: bool = True
+    ca_bundle: str | None = None
+    request_timeout_seconds: float = 60.0
+    poll_interval_seconds: int = 15
+    job_timeout_minutes: int = 30
+    scheme: str = field(init=False, default="https")
+
+    def __post_init__(self) -> None:
+        self.scheme, self.host = host_scheme(self.host)
+        if not self.host:
+            raise InputError("Nexus Dashboard host is required (--host or ND_HOST).")
+        if not self.username:
+            raise InputError("Username is required (--username or ND_USER).")
+        if not self.password:
+            raise InputError("Password is required (ND_PASSWORD).")
+        if not self.domain:
+            # The API answers an empty domain with HTTP 500, so it is caught
+            # here instead.
+            raise InputError(
+                "Login domain is required and cannot be empty "
+                f"(--domain or ND_DOMAIN; try '{DEFAULT_DOMAIN}')."
+            )
+        if self.poll_interval_seconds < 1:
+            raise InputError("--poll-interval must be at least 1 second.")
+        if self.job_timeout_minutes < 1:
+            raise InputError("--timeout must be at least 1 minute.")
+
+    @property
+    def base_url(self) -> str:
+        return f"{self.scheme}://{self.host}"

nac_analytics/core/exceptions.py

@@ -0,0 +1,43 @@
+"""Typed errors, each carrying the process exit code it should produce.
+
+Exit codes are a contract with CI, so they live on the exception rather than
+being chosen at the call site.
+"""
+
+from __future__ import annotations
+
+
+class NacNdError(Exception):
+    """Base error. Anything unclassified exits 1."""
+
+    exit_code: int = 1
+
+
+class JobError(NacNdError):
+    """An analysis job failed, stopped, vanished or timed out."""
+
+    exit_code = 2
+
+
+class AnomalyThresholdError(NacNdError):
+    """New anomalies were found at a severity the caller chose to fail on."""
+
+    exit_code = 3
+
+
+class InputError(NacNdError):
+    """Bad arguments, bad configuration or an unusable input file."""
+
+    exit_code = 4
+
+
+class AuthError(NacNdError):
+    """Authentication or authorisation against Nexus Dashboard failed."""
+
+    exit_code = 5
+
+
+class ApiError(NacNdError):
+    """Nexus Dashboard answered a request with an unexpected status."""
+
+    exit_code = 1

nac_analytics/core/log.py

@@ -0,0 +1,38 @@
+"""Logging configuration shared by the CLI and client."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from nac_analytics.core.redaction import install_redaction_filter
+
+_verbose = False
+
+
+def is_verbose() -> bool:
+    return _verbose
+
+
+def configure_logging(verbose: bool) -> None:
+    """Configure process logging.
+
+    Default mode keeps stderr quiet except for explicit progress lines and
+    errors. Verbose mode logs each HTTP request and API call.
+    """
+    global _verbose
+    _verbose = verbose
+    root = logging.getLogger()
+    if not root.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter("%(levelname)s %(message)s"))
+        root.addHandler(handler)
+    if verbose:
+        root.setLevel(logging.DEBUG)
+        logging.getLogger("httpx").setLevel(logging.DEBUG)
+        logging.getLogger("httpcore").setLevel(logging.DEBUG)
+    else:
+        root.setLevel(logging.WARNING)
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        logging.getLogger("httpcore").setLevel(logging.WARNING)
+    install_redaction_filter(root)

nac_analytics/core/product.py

@@ -0,0 +1,50 @@
+"""The seam every product plugs into.
+
+A :class:`Product` bundles a product's Typer sub-app with the small amount of
+metadata the root CLI needs to mount it (`nac-analytics <product> <verb>`) and
+to load its scoped configuration. Adding a Cisco product to nac-analytics means
+building one of these and registering it in ``nac_analytics.products`` — no
+changes to the root CLI.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import typer
+
+
+@dataclass(frozen=True)
+class Product:
+    """One Cisco product exposed as a `nac-analytics` command group."""
+
+    key: str
+    """Canonical identifier, also the YAML config section (e.g. ``nexus_dashboard``)."""
+
+    cli_name: str
+    """Primary command token (e.g. ``nexus-dashboard``)."""
+
+    app: typer.Typer
+    """The product's Typer sub-app, holding its verbs.
+
+    Its ``help`` first line becomes the product's short description in the root
+    ``--help`` command list.
+    """
+
+    aliases: tuple[str, ...] = ()
+    """Extra command tokens that resolve to this product (e.g. ``nd``)."""
+
+    bootstrap: Callable[[list[str]], list[str]] | None = None
+    """Load this product's scoped config into the environment; return remaining argv."""
+
+    apply_legacy_env: Callable[[], None] | None = None
+    """Optional hook to map retired environment variable names, run after ``.env``."""
+
+    tokens: tuple[str, ...] = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "tokens", (self.cli_name, *self.aliases))
+
+    def matches(self, token: str) -> bool:
+        return token in self.tokens

nac_analytics/core/progress.py

@@ -0,0 +1,10 @@
+"""Simple progress lines for interactive CLI use."""
+
+from __future__ import annotations
+
+import sys
+
+
+def note(message: str) -> None:
+    """Write a short progress update to stderr."""
+    print(message, file=sys.stderr, flush=True)

nac_analytics/core/redaction.py

@@ -0,0 +1,119 @@
+"""Credential redaction for everything this tool logs.
+
+A `logging.Filter` on the root logger and its handlers covers every call site
+without any of them knowing it exists.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+REDACTED = "***REDACTED***"
+
+# Field, header and cookie names used by this codebase and the Nexus Dashboard
+# API. Longest first, so an alternation match cannot stop short at a shorter
+# name.
+SENSITIVE_KEYS: tuple[str, ...] = (
+    "userpasswd",
+    "authcookie",
+    "jwttoken",
+    "password",
+    "passwd",
+    "secret",
+    "token",
+)
+
+_KEYS = "|".join(re.escape(key) for key in SENSITIVE_KEYS)
+
+# `Authorization: Bearer <token>`. Matched by scheme so the scheme word
+# survives and only the credential is replaced. Listing a bare `token ` here
+# would redact the word after "returned no token".
+_SCHEME_RE = re.compile(r"(?i)\b(bearer|basic)(\s+)([A-Za-z0-9\-._~+/]+=*)")
+
+# A JWT, matched on its shape because the session token can be logged with no
+# surrounding field name for the key patterns to key on.
+_JWT_RE = re.compile(r"\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*")
+
+# `"password": "s3cr3t"` -- a quoted value, kept quoted so the surrounding
+# JSON or repr stays readable.
+_QUOTED_RE = re.compile(
+    rf"""(?i)(["']?(?:{_KEYS})["']?\s*[:=]\s*)(["'])(?:\\.|(?!\2).)*\2"""
+)
+
+# `AuthCookie=s3cr3t` -- an unquoted value, ending at the first character that
+# cannot be part of one.
+_BARE_RE = re.compile(rf"""(?i)((?:{_KEYS})["']?\s*[:=]\s*)([^\s,;&"'}}\)\]]+)""")
+
+
+def _quoted_replacement(match: re.Match[str]) -> str:
+    quote = match.group(2)
+    return f"{match.group(1)}{quote}{REDACTED}{quote}"
+
+
+def redact(text: str) -> str:
+    r"""Mask credentials in `text` and flatten it to a single line.
+
+    Newlines are escaped rather than dropped, so a forged `\r\n` cannot write
+    a second log entry. Flattening runs first so a newline inside a quoted
+    value cannot walk a pattern off the end of that value.
+    """
+    text = text.replace("\r", "\\r").replace("\n", "\\n")
+    text = _JWT_RE.sub(REDACTED, text)
+    text = _SCHEME_RE.sub(rf"\1\2{REDACTED}", text)
+    text = _QUOTED_RE.sub(_quoted_replacement, text)
+    return _BARE_RE.sub(rf"\1{REDACTED}", text)
+
+
+class RedactingFilter(logging.Filter):
+    """Scrubs credentials from a log record's message, arguments and traceback.
+
+    The record is interpolated here because a credential can arrive in
+    `record.args` as well as in a preformatted message.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            message = record.getMessage()
+        except (TypeError, ValueError, KeyError, IndexError):
+            # `%`-interpolation of the record's args failed (arity, format or
+            # key mismatch). The uninterpolated args cannot be scanned for
+            # credentials, so they are withheld; the format string still
+            # identifies the call site.
+            message = f"{record.msg} [arguments withheld: interpolation failed]"
+        record.msg = redact(message)
+        # The message is already interpolated, so the arguments are cleared to
+        # stop the handler applying them again.
+        record.args = None
+        if record.exc_info is not None and not record.exc_text:
+            # Rendered here so the traceback is redacted too; the formatter
+            # reuses `exc_text`. Line structure is preserved.
+            exc_text = logging.Formatter().formatException(record.exc_info)
+            record.exc_text = "\n".join(redact(line) for line in exc_text.splitlines())
+        return True
+
+
+def install_redaction_filter(logger: logging.Logger | None = None) -> RedactingFilter:
+    """Install the filter on `logger` (the root logger by default) and its handlers.
+
+    Both are needed: a logger's filters apply only to records logged through
+    that logger, so a root filter alone misses records from child loggers.
+    Idempotent, so repeated calls cannot stack duplicate filters.
+    """
+    target = logger if logger is not None else logging.getLogger()
+    existing = _find_filter(target)
+    if existing is None:
+        existing = RedactingFilter()
+        target.addFilter(existing)
+    for handler in target.handlers:
+        if _find_filter(handler) is None:
+            handler.addFilter(existing)
+    return existing
+
+
+def _find_filter(target: Any) -> RedactingFilter | None:
+    for candidate in target.filters:
+        if isinstance(candidate, RedactingFilter):
+            return candidate
+    return None