iflow-mcp_enuno-unifi-mcp-server 0.2.1__py3-none-any.whl

src/tools/zbf_matrix.py

@@ -0,0 +1,326 @@
+"""Zone-Based Firewall matrix management tools.
+
+⚠️ IMPORTANT: All tools in this file are DEPRECATED as of 2025-11-18.
+
+Endpoint verification on UniFi Express 7 and UDM Pro (API v10.0.156) confirmed
+that the zone policy matrix and application blocking endpoints DO NOT EXIST.
+
+The following endpoints were tested and returned 404:
+- /sites/{siteId}/firewall/policies/zone-matrix
+- /sites/{siteId}/firewall/policies/zones/{zoneId}
+- /sites/{siteId}/firewall/zones/{zoneId}/policies
+- /sites/{siteId}/firewall/zones/{zoneId}/applications/block
+- /sites/{siteId}/firewall/zones/{zoneId}/applications/blocked
+
+Workarounds:
+- Configure zone policies manually in UniFi Console UI
+- Use traditional ACL rules (/sites/{siteId}/acls) for IP-based filtering
+- Use DPI categories for application blocking at network level
+
+See tests/verification/PHASE2_FINDINGS.md for complete verification report.
+"""
+
+from typing import Any
+
+from ..api.client import UniFiClient  # noqa: F401
+from ..config import Settings
+from ..models.zbf_matrix import ApplicationBlockRule, ZonePolicy, ZonePolicyMatrix  # noqa: F401
+from ..utils import audit_action, get_logger, validate_confirmation  # noqa: F401
+
+logger = get_logger(__name__)
+
+
+async def get_zbf_matrix(site_id: str, settings: Settings) -> dict[str, Any]:
+    """Retrieve zone-to-zone policy matrix.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    The zone policy matrix must be configured via the UniFi Console UI.
+    Use traditional ACL rules (/sites/{siteId}/acls) as a workaround.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        settings: Application settings
+
+    Returns:
+        Zone policy matrix with all zones and policies
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        "get_zbf_matrix called but endpoint does not exist in UniFi API v10.0.156. "
+        "Configure zone policies via UniFi Console UI instead."
+    )
+    raise NotImplementedError(
+        "Zone policy matrix endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Configure zone policies manually in UniFi Console. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def get_zone_policies(site_id: str, zone_id: str, settings: Settings) -> list[dict[str, Any]]:
+    """Get policies for a specific zone.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Zone policies must be configured via the UniFi Console UI.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        zone_id: Zone identifier
+        settings: Application settings
+
+    Returns:
+        List of policies for the zone
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"get_zone_policies called for zone {zone_id} but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Zone policies endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Configure zone policies manually in UniFi Console. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def update_zbf_policy(
+    site_id: str,
+    source_zone_id: str,
+    destination_zone_id: str,
+    action: str,
+    settings: Settings,
+    description: str | None = None,
+    priority: int | None = None,
+    enabled: bool = True,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Modify inter-zone firewall policy.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Zone-to-zone policies must be configured via the UniFi Console UI.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        source_zone_id: Source zone identifier
+        destination_zone_id: Destination zone identifier
+        action: Policy action (allow/deny)
+        settings: Application settings
+        description: Policy description
+        priority: Policy priority
+        enabled: Whether policy is enabled
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Updated policy
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"update_zbf_policy called for {source_zone_id} -> {destination_zone_id} "
+        "but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Zone policy update endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Configure zone policies manually in UniFi Console. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def block_application_by_zone(
+    site_id: str,
+    zone_id: str,
+    application_id: str,
+    settings: Settings,
+    action: str = "block",
+    enabled: bool = True,
+    description: str | None = None,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Block applications using zone-based rules.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Application blocking per zone is not available via the API.
+    Use DPI categories for application blocking at the network level instead.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        zone_id: Zone identifier
+        application_id: DPI application identifier
+        settings: Application settings
+        action: Action to take (block/allow)
+        enabled: Whether rule is enabled
+        description: Rule description
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Created application block rule
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"block_application_by_zone called for zone {zone_id}, app {application_id} "
+        "but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Application blocking per zone endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Use DPI categories for application blocking at network level. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def list_blocked_applications(
+    site_id: str, zone_id: str | None = None, settings: Settings | None = None
+) -> list[dict[str, Any]]:
+    """List applications blocked per zone.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Application blocking per zone is not available via the API.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        zone_id: Optional zone identifier to filter by
+        settings: Application settings
+
+    Returns:
+        List of blocked applications
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"list_blocked_applications called for site {site_id} "
+        "but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Blocked applications list endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def get_zone_matrix_policy(
+    site_id: str,
+    source_zone_id: str,
+    destination_zone_id: str,
+    settings: Settings,
+) -> dict[str, Any]:
+    """Get a specific zone-to-zone policy.
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Zone-to-zone policies must be configured via the UniFi Console UI.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        source_zone_id: Source zone identifier
+        destination_zone_id: Destination zone identifier
+        settings: Application settings
+
+    Returns:
+        Zone-to-zone policy details
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"get_zone_matrix_policy called for {source_zone_id} -> {destination_zone_id} "
+        "but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Zone matrix policy endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Configure zone policies manually in UniFi Console. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )
+
+
+async def delete_zbf_policy(
+    site_id: str,
+    source_zone_id: str,
+    destination_zone_id: str,
+    settings: Settings,
+    confirm: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Delete a zone-to-zone policy (revert to default action).
+
+    ⚠️ **DEPRECATED - ENDPOINT DOES NOT EXIST**
+
+    This endpoint has been verified to NOT EXIST in UniFi Network API v10.0.156.
+    Tested on UniFi Express 7 and UDM Pro on 2025-11-18.
+
+    Zone-to-zone policies must be configured via the UniFi Console UI.
+
+    See tests/verification/PHASE2_FINDINGS.md for details.
+
+    Args:
+        site_id: Site identifier
+        source_zone_id: Source zone identifier
+        destination_zone_id: Destination zone identifier
+        settings: Application settings
+        confirm: Confirmation flag (required)
+        dry_run: If True, validate but don't execute
+
+    Returns:
+        Deletion confirmation
+
+    Raises:
+        NotImplementedError: This endpoint does not exist in the UniFi API
+    """
+    logger.warning(
+        f"delete_zbf_policy called for {source_zone_id} -> {destination_zone_id} "
+        "but endpoint does not exist in UniFi API v10.0.156."
+    )
+    raise NotImplementedError(
+        "Zone policy delete endpoint does not exist in UniFi Network API v10.0.156. "
+        "Verified on U7 Express and UDM Pro (2025-11-18). "
+        "Configure zone policies manually in UniFi Console. "
+        "See tests/verification/PHASE2_FINDINGS.md for details."
+    )

src/utils/__init__.py

@@ -0,0 +1,88 @@
+"""Utility modules for UniFi MCP Server."""
+
+from .audit import AuditLogger, audit_action, get_audit_logger, log_audit
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConfirmationRequiredError,
+    NetworkError,
+    RateLimitError,
+    ResourceNotFoundError,
+    UniFiMCPException,
+    ValidationError,
+)
+from .helpers import (
+    build_uri,
+    format_bytes,
+    format_percentage,
+    format_uptime,
+    get_iso_timestamp,
+    get_timestamp,
+    merge_dicts,
+    parse_device_type,
+    sanitize_dict,
+)
+from .logger import get_logger, log_api_request, log_audit_event
+from .sanitize import sanitize_dict as sanitize_sensitive_dict
+from .sanitize import (
+    sanitize_for_logging,
+    sanitize_list,
+    sanitize_log_message,
+    sanitize_sensitive_data,
+)
+from .validators import (
+    validate_confirmation,
+    validate_device_id,
+    validate_ip_address,
+    validate_limit_offset,
+    validate_mac_address,
+    validate_port,
+    validate_site_id,
+)
+
+__all__ = [
+    # Exceptions
+    "UniFiMCPException",
+    "ConfigurationError",
+    "AuthenticationError",
+    "APIError",
+    "RateLimitError",
+    "ResourceNotFoundError",
+    "ValidationError",
+    "NetworkError",
+    "ConfirmationRequiredError",
+    # Audit
+    "AuditLogger",
+    "get_audit_logger",
+    "log_audit",
+    "audit_action",
+    # Logger
+    "get_logger",
+    "log_api_request",
+    "log_audit_event",
+    # Sanitization
+    "sanitize_sensitive_dict",
+    "sanitize_for_logging",
+    "sanitize_list",
+    "sanitize_log_message",
+    "sanitize_sensitive_data",
+    # Validators
+    "validate_mac_address",
+    "validate_ip_address",
+    "validate_port",
+    "validate_site_id",
+    "validate_device_id",
+    "validate_confirmation",
+    "validate_limit_offset",
+    # Helpers
+    "get_timestamp",
+    "get_iso_timestamp",
+    "format_uptime",
+    "format_bytes",
+    "format_percentage",
+    "sanitize_dict",
+    "merge_dicts",
+    "parse_device_type",
+    "build_uri",
+]

src/utils/audit.py

@@ -0,0 +1,213 @@
+"""Audit logging for mutating operations."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .helpers import get_iso_timestamp
+from .logger import get_logger
+
+
+class AuditLogger:
+    """Audit logger for tracking mutating operations."""
+
+    def __init__(self, log_file: str | Path | None = None, log_level: str = "INFO"):
+        """Initialize audit logger.
+
+        Args:
+            log_file: Path to audit log file. If None, uses default location.
+            log_level: Logging level
+        """
+        self.log_file = Path(log_file) if log_file else Path("audit.log")
+        self.logger = get_logger(__name__, log_level)
+
+        # Ensure log directory exists
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    def log_operation(
+        self,
+        operation: str,
+        parameters: dict[str, Any],
+        result: str,
+        user: str | None = None,
+        site_id: str | None = None,
+        dry_run: bool = False,
+        error: str | None = None,
+    ) -> None:
+        """Log a mutating operation.
+
+        Args:
+            operation: Name of the operation (e.g., "create_firewall_rule")
+            parameters: Parameters passed to the operation
+            result: Result of the operation ("success", "failed", "dry_run")
+            user: User who performed the operation (optional)
+            error: Error message if the operation failed (optional)
+            site_id: Site ID where operation was performed
+            dry_run: Whether this was a dry run
+        """
+        timestamp = get_iso_timestamp()
+
+        # Create audit record
+        audit_record = {
+            "timestamp": timestamp,
+            "operation": operation,
+            "parameters": parameters,
+            "result": result,
+            "dry_run": dry_run,
+        }
+
+        if user:
+            audit_record["user"] = user
+
+        if site_id:
+            audit_record["site_id"] = site_id
+
+        if error:
+            audit_record["error"] = error
+
+        # Log to file
+        try:
+            with open(self.log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(audit_record) + "\n")
+        except Exception as e:
+            self.logger.error(f"Failed to write audit log: {e}")
+
+        # Log to application logger
+        log_message = f"AUDIT: {operation} - {result}"
+        if dry_run:
+            log_message += " (DRY RUN)"
+
+        if result == "success":
+            self.logger.info(log_message, extra=audit_record)
+        elif result == "failed":
+            self.logger.warning(log_message, extra=audit_record)
+        else:
+            self.logger.info(log_message, extra=audit_record)
+
+    def get_recent_operations(
+        self, limit: int = 100, operation: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Get recent audit log entries.
+
+        Args:
+            limit: Maximum number of entries to return
+            operation: Filter by operation name (optional)
+
+        Returns:
+            List of audit log entries
+        """
+        if not self.log_file.exists():
+            return []
+
+        entries = []
+        try:
+            with open(self.log_file, encoding="utf-8") as f:
+                # Read file in reverse to get most recent entries first
+                lines = f.readlines()
+                for line in reversed(lines):
+                    if not line.strip():
+                        continue
+
+                    try:
+                        entry = json.loads(line)
+                        if operation is None or entry.get("operation") == operation:
+                            entries.append(entry)
+
+                        if len(entries) >= limit:
+                            break
+                    except json.JSONDecodeError:
+                        self.logger.warning(f"Invalid JSON in audit log: {line}")
+                        continue
+
+        except Exception as e:
+            self.logger.error(f"Failed to read audit log: {e}")
+
+        return entries
+
+
+# Global audit logger instance
+_audit_logger: AuditLogger | None = None
+
+
+def get_audit_logger(log_file: str | Path | None = None, log_level: str = "INFO") -> AuditLogger:
+    """Get or create the global audit logger instance.
+
+    Args:
+        log_file: Path to audit log file
+        log_level: Logging level
+
+    Returns:
+        AuditLogger instance
+    """
+    global _audit_logger
+
+    if _audit_logger is None:
+        _audit_logger = AuditLogger(log_file, log_level)
+
+    return _audit_logger
+
+
+def log_audit(
+    operation: str,
+    parameters: dict[str, Any],
+    result: str,
+    user: str | None = None,
+    site_id: str | None = None,
+    dry_run: bool = False,
+    error: str | None = None,
+    log_file: str | Path | None = None,
+) -> None:
+    """Convenience function to log an audit entry.
+
+    Args:
+        operation: Name of the operation
+        parameters: Parameters passed to the operation
+        result: Result of the operation
+        user: User who performed the operation
+        site_id: Site ID where operation was performed
+        dry_run: Whether this was a dry run
+        error: Error message if the operation failed
+        log_file: Path to audit log file
+    """
+    logger = get_audit_logger(log_file)
+    logger.log_operation(operation, parameters, result, user, site_id, dry_run, error)
+
+
+async def audit_action(
+    settings: Any,
+    action_type: str,
+    resource_type: str,
+    resource_id: str,
+    site_id: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Audit a mutating action.
+
+    Args:
+        settings: Application settings
+        action_type: Type of action (e.g., "create_firewall_zone")
+        resource_type: Type of resource (e.g., "firewall_zone")
+        resource_id: Resource identifier
+        site_id: Site identifier
+        details: Additional details about the action
+    """
+    parameters = {
+        "action_type": action_type,
+        "resource_type": resource_type,
+        "resource_id": resource_id,
+        "site_id": site_id,
+    }
+
+    if details:
+        parameters["details"] = details  # type: ignore[assignment]
+
+    # Get audit log file from settings if available
+    log_file = getattr(settings, "audit_log_file", None)
+
+    log_audit(
+        operation=action_type,
+        parameters=parameters,
+        result="success",
+        site_id=site_id,
+        log_file=log_file,
+    )