unifi-network-maps 1.4.11__tar.gz → 1.4.13__tar.gz

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.13] - 2026-01-25
+### Fixed
+- Path Traversal Vulnerability in File Operations
+- Cache Directory Symlink Attack vector
+
+### Changed
+- Improved escaping in Markdown Output
+- Made logging less chatty, moved messages to debug level
+
+## [1.4.12] - 2026-01-21
+### Added
+- Filter UniFi clients with --only-unifi, and not only neighbors
+
+### Fixed
+- inconsistencies in --only-unifi
+
 ## [1.4.11] - 2026-01-19
 ### Added
 - Add data-edge-left/right attributes to SVG paths
@@ -176,8 +192,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Introduced SVG renderer and tree layout fixes.
 - Increased test coverage and added coverage tooling.
 
-[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...HEAD
-[1.4.11]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.10...v1.4.111
+[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.13...HEAD
+[1.4.13]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.13
+[1.4.12]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.12
+[1.4.11]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.10...v1.4.11
 [1.4.10]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.9...v1.4.10
 [1.4.9]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.8...v1.4.9
 [1.4.8]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.7...v1.4.8

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.11
+Version: 1.4.13
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -32,7 +32,7 @@ Requires-Dist: pre-commit==4.5.1; extra == "dev"
 Requires-Dist: pytest==9.0.2; extra == "dev"
 Requires-Dist: pytest-cov==7.0.0; extra == "dev"
 Requires-Dist: pyright==1.1.408; extra == "dev"
-Requires-Dist: ruff==0.14.13; extra == "dev"
+Requires-Dist: ruff==0.14.14; extra == "dev"
 Dynamic: license-file
 
 # unifi-network-maps
@@ -223,7 +223,7 @@ Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
 - `--include-clients`: add active wired clients as leaf nodes.
 - `--client-scope wired|wireless|all`: which client types to include (default wired).
-- `--only-unifi`: only include neighbors that are UniFi devices.
+- `--only-unifi`: only include neighbors that are UniFi devices; when clients are included, filters to UniFi-managed clients (by explicit UniFi flags or vendor/OUI).
 - `--no-cache`: disable UniFi API cache reads and writes.
 
 Mermaid:

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/README.md

@@ -186,7 +186,7 @@ Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
 - `--include-clients`: add active wired clients as leaf nodes.
 - `--client-scope wired|wireless|all`: which client types to include (default wired).
-- `--only-unifi`: only include neighbors that are UniFi devices.
+- `--only-unifi`: only include neighbors that are UniFi devices; when clients are included, filters to UniFi-managed clients (by explicit UniFi flags or vendor/OUI).
 - `--no-cache`: disable UniFi API cache reads and writes.
 
 Mermaid:

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools==80.9.0", "wheel==0.45.1"]
+requires = ["setuptools==80.10.1", "wheel==0.46.3"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.4.11"
+version = "1.4.13"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -44,7 +44,7 @@ dev = [
   "pytest==9.0.2",
   "pytest-cov==7.0.0",
   "pyright==1.1.408",
-  "ruff==0.14.13"
+  "ruff==0.14.14"
 ]
 
 [project.scripts]

unifi_network_maps-1.4.13/src/unifi_network_maps/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.4.13"

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/adapters/config.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass
+from pathlib import Path
+
+from ..io.paths import resolve_env_file
 
 
 def _parse_bool(value: str | None, default: bool = True) -> bool:
@@ -26,13 +29,14 @@ class Config:
     verify_ssl: bool
 
     @classmethod
-    def from_env(cls, *, env_file: str | None = None) -> Config:
+    def from_env(cls, *, env_file: str | Path | None = None) -> Config:
         if env_file:
             try:
                 from dotenv import load_dotenv
             except ImportError:
                 raise ValueError("python-dotenv required for --env-file") from None
-            load_dotenv(dotenv_path=env_file)
+            env_path = resolve_env_file(env_file)
+            load_dotenv(dotenv_path=env_path)
         url = os.environ.get("UNIFI_URL", "").strip()
         site = os.environ.get("UNIFI_SITE", "default").strip()
         user = os.environ.get("UNIFI_USER", "").strip()

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/adapters/unifi.py

@@ -7,6 +7,7 @@ import json
 import logging
 import os
 import stat
+import tempfile
 import time
 from collections.abc import Callable, Iterator, Sequence
 from concurrent.futures import ThreadPoolExecutor
@@ -15,6 +16,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import IO, TYPE_CHECKING
 
+from ..io.paths import resolve_cache_dir
 from .config import Config
 
 if TYPE_CHECKING:
@@ -24,7 +26,15 @@ logger = logging.getLogger(__name__)
 
 
 def _cache_dir() -> Path:
-    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_network_maps"))
+    default_dir = ".cache/unifi_network_maps"
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        default_dir = str(Path(tempfile.gettempdir()) / f"unifi_network_maps_pytest_{os.getpid()}")
+    value = os.environ.get("UNIFI_CACHE_DIR", default_dir)
+    try:
+        return resolve_cache_dir(value)
+    except ValueError as exc:
+        logger.warning("Invalid UNIFI_CACHE_DIR (%s); using default: %s", value, exc)
+        return resolve_cache_dir(".cache/unifi_network_maps")
 
 
 def _device_attr(device: object, name: str) -> object | None:
@@ -377,13 +387,13 @@ def fetch_devices(
         cached = None
         stale_cached, cache_age = None, None
     if cached is not None:
-        logger.info("Using cached devices (%d)", len(cached))
+        logger.debug("Using cached devices (%d)", len(cached))
         return cached
 
     try:
         controller = _init_controller(config, is_udm_pro=True)
     except UnifiAuthenticationError:
-        logger.info("UDM Pro authentication failed, retrying legacy auth")
+        logger.debug("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
     def _fetch() -> Sequence[object]:
@@ -402,7 +412,7 @@ def fetch_devices(
         raise
     if use_cache:
         _save_cache(cache_path, _serialize_devices_for_cache(devices))
-    logger.info("Fetched %d devices", len(devices))
+    logger.debug("Fetched %d devices", len(devices))
     return devices
 
 
@@ -428,13 +438,13 @@ def fetch_clients(
         cached = None
         stale_cached, cache_age = None, None
     if cached is not None:
-        logger.info("Using cached clients (%d)", len(cached))
+        logger.debug("Using cached clients (%d)", len(cached))
         return cached
 
     try:
         controller = _init_controller(config, is_udm_pro=True)
     except UnifiAuthenticationError:
-        logger.info("UDM Pro authentication failed, retrying legacy auth")
+        logger.debug("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
     def _fetch() -> Sequence[object]:
@@ -453,5 +463,5 @@ def fetch_clients(
         raise
     if use_cache:
         _save_cache(cache_path, clients)
-    logger.info("Fetched %d clients", len(clients))
+    logger.debug("Fetched %d clients", len(clients))
     return clients

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/cli/main.py

@@ -4,10 +4,17 @@ from __future__ import annotations
 
 import argparse
 import logging
+from pathlib import Path
 
 from ..adapters.config import Config
 from ..io.export import write_output
 from ..io.mock_data import load_mock_data
+from ..io.paths import (
+    resolve_env_file,
+    resolve_mock_data_path,
+    resolve_output_path,
+    resolve_theme_path,
+)
 from ..render.legend import render_legend_only, resolve_legend_style
 from ..render.theme import resolve_themes
 from .args import build_parser
@@ -16,7 +23,7 @@ from .render import render_lldp_format, render_standard_format
 logger = logging.getLogger(__name__)
 
 
-def _load_dotenv(env_file: str | None = None) -> None:
+def _load_dotenv(env_file: str | Path | None = None) -> None:
     try:
         from dotenv import load_dotenv
     except ImportError:
@@ -30,6 +37,36 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
     return parser.parse_args(argv)
 
 
+class _DowngradeInfoToDebugFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.name.startswith("unifi_controller_api") and record.levelno == logging.INFO:
+            record.levelno = logging.DEBUG
+            record.levelname = logging.getLevelName(logging.DEBUG)
+        return True
+
+
+def _downgrade_unifi_controller_logs() -> logging.Filter:
+    return _DowngradeInfoToDebugFilter()
+
+
+def _validate_paths(args: argparse.Namespace) -> bool:
+    try:
+        if args.env_file:
+            resolve_env_file(args.env_file)
+        if args.mock_data:
+            resolve_mock_data_path(args.mock_data, require_exists=False)
+        if args.theme_file:
+            resolve_theme_path(args.theme_file, require_exists=False)
+        if args.generate_mock:
+            resolve_output_path(args.generate_mock, format_name="mock")
+        if args.output:
+            resolve_output_path(args.output, format_name=args.format)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return False
+    return True
+
+
 def _load_config(args: argparse.Namespace) -> Config | None:
     try:
         _load_dotenv(args.env_file)
@@ -59,7 +96,8 @@ def _handle_generate_mock(args: argparse.Namespace) -> int | None:
         wireless_client_count=max(0, args.mock_wireless_clients),
     )
     content = mock_payload_json(options)
-    write_output(content, output_path=args.generate_mock, stdout=args.stdout)
+    output_kwargs = {"format_name": "mock"} if args.generate_mock else {}
+    write_output(content, output_path=args.generate_mock, stdout=args.stdout, **output_kwargs)
     return 0
 
 
@@ -81,7 +119,11 @@ def _load_runtime_context(
 
 def main(argv: list[str] | None = None) -> int:
     logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    for handler in logging.getLogger().handlers:
+        handler.addFilter(_downgrade_unifi_controller_logs())
     args = _parse_args(argv)
+    if not _validate_paths(args):
+        return 2
     mock_result = _handle_generate_mock(args)
     if mock_result is not None:
         return mock_result
@@ -107,7 +149,8 @@ def main(argv: list[str] | None = None) -> int:
             markdown=args.markdown,
             theme=mermaid_theme,
         )
-        write_output(content, output_path=args.output, stdout=args.stdout)
+        output_kwargs = {"format_name": args.format} if args.output else {}
+        write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
         return 0
 
     if args.format == "lldp-md":

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/cli/render.py

@@ -62,7 +62,12 @@ def render_mermaid_output(
         direction=args.direction,
         groups=groups,
         group_order=group_order,
-        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        node_types=build_node_type_map(
+            devices,
+            clients,
+            client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
+        ),
         theme=mermaid_theme,
     )
     if args.markdown:
@@ -97,13 +102,23 @@ def render_svg_output(
 
         return render_svg_isometric(
             edges,
-            node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+            node_types=build_node_type_map(
+                devices,
+                clients,
+                client_mode=args.client_scope,
+                only_unifi=args.only_unifi,
+            ),
             options=options,
             theme=svg_theme,
         )
     return render_svg(
         edges,
-        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        node_types=build_node_type_map(
+            devices,
+            clients,
+            client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
+        ),
         options=options,
         theme=svg_theme,
     )
@@ -190,8 +205,10 @@ def render_lldp_format(
         include_ports=args.include_ports,
         show_clients=args.include_clients,
         client_mode=args.client_scope,
+        only_unifi=args.only_unifi,
     )
-    write_output(content, output_path=args.output, stdout=args.stdout)
+    output_kwargs = {"format_name": args.format} if args.output else {}
+    write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
     return 0
 
 
@@ -251,5 +268,6 @@ def render_standard_format(
         logging.error("Unsupported format: %s", args.format)
         return 2
 
-    write_output(content, output_path=args.output, stdout=args.stdout)
+    output_kwargs = {"format_name": args.format} if args.output else {}
+    write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
     return 0

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/cli/runtime.py

@@ -95,6 +95,7 @@ def build_edges_with_clients(
             device_index,
             include_ports=args.include_ports,
             client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
         )
     return edges, clients
 
@@ -153,5 +154,10 @@ def resolve_mkdocs_client_ports(
         clients = list(fetch_clients(config, site=site))
     else:
         clients = mock_clients
-    client_ports = build_client_port_map(devices, clients, client_mode=args.client_scope)
+    client_ports = build_client_port_map(
+        devices,
+        clients,
+        client_mode=args.client_scope,
+        only_unifi=args.only_unifi,
+    )
     return client_ports, None

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/io/export.py

@@ -7,10 +7,19 @@ import sys
 import tempfile
 from pathlib import Path
 
+from .paths import resolve_output_path
 
-def write_output(content: str, *, output_path: str | None, stdout: bool) -> None:
+
+def write_output(
+    content: str,
+    *,
+    output_path: str | Path | None,
+    stdout: bool,
+    format_name: str | None = None,
+) -> None:
     if output_path:
-        _write_atomic(Path(output_path), content)
+        resolved = resolve_output_path(output_path, format_name=format_name)
+        _write_atomic(resolved, content)
     if stdout or not output_path:
         sys.stdout.write(content)
 

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/io/mkdocs_assets.py

@@ -5,10 +5,12 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..render.templating import render_template
+from .paths import resolve_output_file
 
 
-def write_mkdocs_sidebar_assets(output_path: str) -> None:
-    output_dir = Path(output_path).resolve().parent
+def write_mkdocs_sidebar_assets(output_path: str | Path) -> None:
+    resolved = resolve_output_file(output_path, extensions=None, label="MkDocs output file")
+    output_dir = resolved.parent
     assets_dir = output_dir / "assets"
     assets_dir.mkdir(parents=True, exist_ok=True)
     (assets_dir / "legend.js").write_text(

{unifi_network_maps-1.4.11 → unifi_network_maps-1.4.13}/src/unifi_network_maps/io/mock_data.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import json
-from pathlib import Path
+
+from .paths import resolve_mock_data_path
 
 
 def _as_list(value: object, name: str) -> list[object]:
@@ -15,7 +16,8 @@ def _as_list(value: object, name: str) -> list[object]:
 
 
 def load_mock_data(path: str) -> tuple[list[object], list[object]]:
-    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    resolved = resolve_mock_data_path(path)
+    payload = json.loads(resolved.read_text(encoding="utf-8"))
     if not isinstance(payload, dict):
         raise ValueError("Mock data must be a JSON object")
     devices = _as_list(payload.get("devices"), "devices")

unifi_network_maps-1.4.13/src/unifi_network_maps/io/paths.py

@@ -0,0 +1,197 @@
+"""Path validation helpers for user-supplied file system inputs."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def _safe_home_dir() -> Path | None:
+    try:
+        return Path.home().resolve()
+    except Exception:
+        return None
+
+
+def _base_roots() -> list[Path]:
+    roots = [Path.cwd().resolve()]
+    home = _safe_home_dir()
+    if home:
+        roots.append(home)
+    try:
+        roots.append(Path(tempfile.gettempdir()).resolve())
+    except Exception:
+        pass
+    return roots
+
+
+def _extra_roots_from_env() -> list[Path]:
+    extra = os.environ.get("UNIFI_ALLOWED_PATHS", "")
+    roots: list[Path] = []
+    if extra:
+        for raw in extra.split(os.pathsep):
+            raw = raw.strip()
+            if raw:
+                roots.append(Path(raw).expanduser().resolve())
+    return roots
+
+
+def _allowed_roots() -> tuple[Path, ...]:
+    roots = _base_roots() + _extra_roots_from_env()
+    seen: set[str] = set()
+    unique: list[Path] = []
+    for root in roots:
+        key = str(root)
+        if key not in seen:
+            seen.add(key)
+            unique.append(root)
+    return tuple(unique)
+
+
+def _resolve_user_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve(strict=False)
+
+
+def _ensure_within_allowed(path: Path, roots: Iterable[Path], *, label: str) -> None:
+    for root in roots:
+        try:
+            path.relative_to(root)
+        except ValueError:
+            continue
+        else:
+            return
+    root_list = ", ".join(str(root) for root in roots)
+    raise ValueError(f"{label} must be within: {root_list}")
+
+
+def _ensure_no_symlink(path: Path, *, label: str) -> None:
+    if path.exists() and path.is_symlink():
+        raise ValueError(f"{label} must not be a symlink: {path}")
+
+
+def _ensure_no_symlink_in_parents(path: Path, *, label: str) -> None:
+    for parent in path.parents:
+        if parent.exists() and parent.is_symlink():
+            raise ValueError(f"{label} parent must not be a symlink: {parent}")
+
+
+def _normalize_extensions(extensions: Iterable[str]) -> set[str]:
+    normalized = set()
+    for ext in extensions:
+        ext = ext.strip().lower()
+        if not ext:
+            continue
+        if not ext.startswith("."):
+            ext = f".{ext}"
+        normalized.add(ext)
+    return normalized
+
+
+def _ensure_extension(
+    path: Path,
+    extensions: Iterable[str] | None,
+    *,
+    label: str,
+    allow_missing: bool = False,
+) -> None:
+    if not extensions:
+        return
+    allowed = _normalize_extensions(extensions)
+    suffix = path.suffix.lower()
+    if not suffix:
+        if allow_missing:
+            return
+        raise ValueError(f"{label} must have one of: {', '.join(sorted(allowed))}")
+    if suffix not in allowed:
+        raise ValueError(f"{label} must have one of: {', '.join(sorted(allowed))}")
+
+
+def resolve_input_file(
+    path: str | Path,
+    *,
+    extensions: Iterable[str] | None,
+    label: str,
+    require_exists: bool = True,
+) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label=label)
+    _ensure_extension(resolved, extensions, label=label)
+    if require_exists:
+        if not resolved.exists():
+            raise ValueError(f"{label} does not exist: {resolved}")
+        if not resolved.is_file():
+            raise ValueError(f"{label} must be a file: {resolved}")
+    return resolved
+
+
+def resolve_output_file(
+    path: str | Path,
+    *,
+    extensions: Iterable[str] | None,
+    label: str,
+    allow_missing_extension: bool = False,
+) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label=label)
+    _ensure_extension(
+        resolved,
+        extensions,
+        label=label,
+        allow_missing=allow_missing_extension,
+    )
+    return resolved
+
+
+def resolve_env_file(path: str | Path) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label="Env file")
+    if not (resolved.name.startswith(".env") or resolved.name.endswith(".env")):
+        raise ValueError("Env file must end with .env")
+    if resolved.exists() and not resolved.is_file():
+        raise ValueError(f"Env file must be a file: {resolved}")
+    return resolved
+
+
+def resolve_mock_data_path(path: str | Path, *, require_exists: bool = True) -> Path:
+    return resolve_input_file(
+        path,
+        extensions={".json"},
+        label="Mock data file",
+        require_exists=require_exists,
+    )
+
+
+def resolve_theme_path(path: str | Path, *, require_exists: bool = True) -> Path:
+    return resolve_input_file(
+        path,
+        extensions={".yml", ".yaml"},
+        label="Theme file",
+        require_exists=require_exists,
+    )
+
+
+def resolve_output_path(path: str | Path, *, format_name: str | None) -> Path:
+    extensions: set[str] | None
+    if format_name == "svg" or format_name == "svg-iso":
+        extensions = {".svg"}
+    elif format_name == "mock":
+        extensions = {".json"}
+    elif format_name == "mermaid":
+        extensions = {".md", ".mermaid", ".mmd"}
+    elif format_name == "lldp-md":
+        extensions = {".md"}
+    elif format_name == "mkdocs":
+        extensions = {".md"}
+    else:
+        extensions = None
+    return resolve_output_file(path, extensions=extensions, label="Output file")
+
+
+def resolve_cache_dir(path: str | Path) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label="Cache directory")
+    _ensure_no_symlink(resolved, label="Cache directory")
+    _ensure_no_symlink_in_parents(resolved, label="Cache directory")
+    return resolved