unifi-network-maps 1.4.12__tar.gz → 1.4.14__tar.gz

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/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.14] - 2026-02-01
+### Added
+- JSON output with VLAN inventory
+
+### Changed
+- Added log message when /tmp can't be resolved
+
+## [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
@@ -183,7 +199,9 @@ 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.12...HEAD
+[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.14...HEAD
+[1.4.14]:https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.11...v1.4.14
+[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

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.12
+Version: 1.4.14
 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
@@ -147,6 +147,12 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+JSON payload (devices + clients + VLAN inventory):
+
+```bash
+unifi-network-maps --format json --output ./payload.json
+```
+
 ## Home Assistant integration
 
 The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
@@ -238,7 +244,7 @@ SVG:
 - `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
 
 Output:
-- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs|json`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
 - `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/README.md

@@ -110,6 +110,12 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+JSON payload (devices + clients + VLAN inventory):
+
+```bash
+unifi-network-maps --format json --output ./payload.json
+```
+
 ## Home Assistant integration
 
 The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
@@ -201,7 +207,7 @@ SVG:
 - `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
 
 Output:
-- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs|json`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
 - `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools==80.9.0", "wheel==0.45.1"]
+requires = ["setuptools==80.10.2", "wheel==0.46.3"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.4.12"
+version = "1.4.14"
 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.14/src/unifi_network_maps/__init__.py

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

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/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.12 → unifi_network_maps-1.4.14}/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,8 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import IO, TYPE_CHECKING
 
+from ..io.paths import resolve_cache_dir
+from ..model.vlans import build_vlan_info, normalize_networks
 from .config import Config
 
 if TYPE_CHECKING:
@@ -24,7 +27,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:
@@ -160,6 +171,19 @@ def _serialize_devices_for_cache(devices: Sequence[object]) -> list[dict[str, ob
     return [_serialize_device_for_cache(device) for device in devices]
 
 
+def _serialize_network_for_cache(network: object) -> dict[str, object]:
+    return {
+        "name": _first_attr(network, "name", "network_name", "networkName"),
+        "vlan": _first_attr(network, "vlan", "vlan_id", "vlanId", "vlanid"),
+        "vlan_enabled": _first_attr(network, "vlan_enabled", "vlanEnabled"),
+        "purpose": _first_attr(network, "purpose"),
+    }
+
+
+def _serialize_networks_for_cache(networks: Sequence[object]) -> list[dict[str, object]]:
+    return [_serialize_network_for_cache(network) for network in networks]
+
+
 def _cache_lock_path(path: Path) -> Path:
     return path.with_suffix(path.suffix + ".lock")
 
@@ -377,13 +401,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 +426,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 +452,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 +477,98 @@ 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
+
+
+def fetch_networks(
+    config: Config,
+    *,
+    site: str | None = None,
+    use_cache: bool = True,
+) -> Sequence[object]:
+    """Fetch network inventory from UniFi Controller."""
+    try:
+        from unifi_controller_api import UnifiAuthenticationError
+    except ImportError as exc:
+        raise RuntimeError("Missing dependency: unifi-controller-api") from exc
+
+    site_name = site or config.site
+    ttl_seconds = _cache_ttl_seconds()
+    cache_path = _cache_dir() / f"networks_{_cache_key(config.url, site_name)}.json"
+    if use_cache and _is_cache_dir_safe(cache_path.parent):
+        cached = _load_cache(cache_path, ttl_seconds)
+        stale_cached, cache_age = _load_cache_with_age(cache_path)
+    else:
+        cached = None
+        stale_cached, cache_age = None, None
+    if cached is not None:
+        logger.debug("Using cached networks (%d)", len(cached))
+        return cached
+
+    try:
+        controller = _init_controller(config, is_udm_pro=True)
+    except UnifiAuthenticationError:
+        logger.debug("UDM Pro authentication failed, retrying legacy auth")
+        controller = _init_controller(config, is_udm_pro=False)
+
+    def _fetch() -> Sequence[object]:
+        try:
+            return controller.get_unifi_site_networkconf(site_name=site_name, raw=False)
+        except Exception as exc:  # noqa: BLE001 - fallback to raw network data
+            logger.warning("Networkconf model parse failed; retrying raw fetch: %s", exc)
+            return controller.get_unifi_site_networkconf(site_name=site_name, raw=True)
+
+    try:
+        networks = _call_with_retries("network fetch", _fetch)
+    except Exception as exc:  # noqa: BLE001 - fallback to cache
+        if stale_cached is not None:
+            logger.warning(
+                "Network fetch failed; using stale cache (%ds old): %s",
+                int(cache_age or 0),
+                exc,
+            )
+            return stale_cached
+        raise
+    if use_cache:
+        _save_cache(cache_path, _serialize_networks_for_cache(networks))
+    logger.debug("Fetched %d networks", len(networks))
+    return networks
+
+
+def fetch_payload(
+    config: Config,
+    *,
+    site: str | None = None,
+    include_clients: bool = True,
+    use_cache: bool = True,
+) -> dict[str, list[object] | list[dict[str, object]]]:
+    """Fetch devices, clients, and VLAN inventory for payload output."""
+    devices = list(fetch_devices(config, site=site, detailed=True, use_cache=use_cache))
+    clients = _fetch_payload_clients(
+        config,
+        site=site,
+        include_clients=include_clients,
+        use_cache=use_cache,
+    )
+    networks = list(fetch_networks(config, site=site, use_cache=use_cache))
+    normalized_networks = normalize_networks(networks)
+    vlan_info = build_vlan_info(clients, normalized_networks)
+    return {
+        "devices": devices,
+        "clients": clients,
+        "networks": normalized_networks,
+        "vlan_info": vlan_info,
+    }
+
+
+def _fetch_payload_clients(
+    config: Config,
+    *,
+    site: str | None,
+    include_clients: bool,
+    use_cache: bool,
+) -> list[object]:
+    if not include_clients:
+        return []
+    return list(fetch_clients(config, site=site, use_cache=use_cache))

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/src/unifi_network_maps/cli/args.py

@@ -125,7 +125,7 @@ def add_general_render_args(parser: argparse._ArgumentGroup) -> None:
     parser.add_argument(
         "--format",
         default="mermaid",
-        choices=["mermaid", "svg", "svg-iso", "lldp-md", "mkdocs"],
+        choices=["mermaid", "svg", "svg-iso", "lldp-md", "mkdocs", "json"],
         help="Output format",
     )
     parser.add_argument(

{unifi_network_maps-1.4.12 → unifi_network_maps-1.4.14}/src/unifi_network_maps/cli/main.py

@@ -3,11 +3,21 @@
 from __future__ import annotations
 
 import argparse
+import json
 import logging
+from pathlib import Path
 
 from ..adapters.config import Config
+from ..adapters.unifi import fetch_payload
 from ..io.export import write_output
-from ..io.mock_data import load_mock_data
+from ..io.mock_data import load_mock_data, load_mock_payload
+from ..io.paths import (
+    resolve_env_file,
+    resolve_mock_data_path,
+    resolve_output_path,
+    resolve_theme_path,
+)
+from ..model.vlans import build_vlan_info, normalize_networks
 from ..render.legend import render_legend_only, resolve_legend_style
 from ..render.theme import resolve_themes
 from .args import build_parser
@@ -16,7 +26,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 +40,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 +99,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
 
 
@@ -79,9 +120,45 @@ def _load_runtime_context(
     return config, site, None, None
 
 
+def _handle_json_format(
+    args: argparse.Namespace,
+    *,
+    config: Config | None,
+    site: str,
+) -> int | None:
+    if args.format != "json":
+        return None
+    payload: dict[str, list[object] | list[dict[str, object]]]
+    if args.mock_data:
+        payload = load_mock_payload(args.mock_data)
+        if not args.include_clients:
+            payload["clients"] = []
+        networks = normalize_networks(payload.get("networks", []))
+        payload["networks"] = networks
+        payload["vlan_info"] = build_vlan_info(payload.get("clients", []), networks)
+    else:
+        if config is None:
+            logging.error("Config required to run")
+            return 2
+        payload = fetch_payload(
+            config,
+            site=site,
+            include_clients=args.include_clients,
+            use_cache=not args.no_cache,
+        )
+    content = json.dumps(payload, indent=2, sort_keys=True)
+    output_kwargs = {"format_name": args.format} if args.output else {}
+    write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
+    return 0
+
+
 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
@@ -90,6 +167,9 @@ def main(argv: list[str] | None = None) -> int:
     except ValueError as exc:
         logging.error(str(exc))
         return 2
+    payload_result = _handle_json_format(args, config=config, site=site)
+    if payload_result is not None:
+        return payload_result
     try:
         mermaid_theme, svg_theme = resolve_themes(args.theme_file)
     except Exception as exc:  # noqa: BLE001
@@ -107,7 +187,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.12 → unifi_network_maps-1.4.14}/src/unifi_network_maps/cli/render.py

@@ -207,7 +207,8 @@ def render_lldp_format(
         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
 
 
@@ -267,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.12 → unifi_network_maps-1.4.14}/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.12 → unifi_network_maps-1.4.14}/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.14/src/unifi_network_maps/io/mock_data.py

@@ -0,0 +1,42 @@
+"""Load mock UniFi data from JSON fixtures."""
+
+from __future__ import annotations
+
+import json
+
+from .paths import resolve_mock_data_path
+
+
+def _as_list(value: object, name: str) -> list[object]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    raise ValueError(f"Mock data field '{name}' must be a list")
+
+
+def load_mock_data(path: str) -> tuple[list[object], list[object]]:
+    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")
+    clients = _as_list(payload.get("clients"), "clients")
+    return devices, clients
+
+
+def load_mock_payload(path: str) -> dict[str, list[object] | list[dict[str, object]]]:
+    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")
+    clients = _as_list(payload.get("clients"), "clients")
+    networks = _as_list(payload.get("networks"), "networks")
+    vlan_info = _as_list(payload.get("vlan_info"), "vlan_info")
+    return {
+        "devices": devices,
+        "clients": clients,
+        "networks": networks,
+        "vlan_info": vlan_info,
+    }