lanscape 1.3.5a1__tar.gz → 1.3.5a2__tar.gz

{lanscape-1.3.5a1/lanscape.egg-info → lanscape-1.3.5a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lanscape
-Version: 1.3.5a1
+Version: 1.3.5a2
 Summary: A python based local network scanner
 Author-email: Michael Dennis <michael@dipduo.com>
 License-Expression: MIT

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/app_scope.py

@@ -5,7 +5,6 @@ Resource and environment management utilities for Lanscape.
 
 from pathlib import Path
 import json
-import sys
 import re
 
 

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/decorators.py

@@ -18,9 +18,12 @@ class JobStats:
     """
     Tracks statistics for job execution, including running, finished, and timing data.
     """
-    running: DefaultDict[str, int] = field(default_factory=lambda: defaultdict(int))
-    finished: DefaultDict[str, int] = field(default_factory=lambda: defaultdict(int))
-    timing: DefaultDict[str, float] = field(default_factory=lambda: defaultdict(float))
+    running: DefaultDict[str, int] = field(
+        default_factory=lambda: defaultdict(int))
+    finished: DefaultDict[str, int] = field(
+        default_factory=lambda: defaultdict(int))
+    timing: DefaultDict[str, float] = field(
+        default_factory=lambda: defaultdict(float))
 
     def __str__(self):
         """Return a formatted string representation of the job statistics."""
@@ -57,7 +60,8 @@ class JobStatsMixin:  # pylint: disable=too-few-public-methods
 
 def job_tracker(func):
     """
-    Decorator to track job statistics for a method, including running count, finished count, and average timing.
+    Decorator to track job statistics for a method,
+    including running count, finished count, and average timing.
     """
     def get_fxn_src_name(func, first_arg) -> str:
         """
@@ -112,7 +116,8 @@ def job_tracker(func):
 
 def terminator(func):
     """
-    Decorator designed specifically for the SubnetScanner class, helps facilitate termination of a job.
+    Decorator designed specifically for the SubnetScanner class,
+    helps facilitate termination of a job.
     """
     def wrapper(*args, **kwargs):
         """Wrap the function to check if the scan is running before execution."""

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/errors.py

@@ -1,3 +1,9 @@
+"""
+Custom exceptions used by the lanscape application.
+
+This module contains custom exception classes for handling various error cases
+in the network scanning and device management operations.
+"""
 
 
 class SubnetTooLargeError(Exception):
@@ -9,12 +15,16 @@ class SubnetTooLargeError(Exception):
 
 
 class SubnetScanTerminationFailure(Exception):
+    """Exception raised when subnet scanning threads cannot be terminated properly."""
+
     def __init__(self, running_threads):
         super().__init__(
             f'Unable to terminate active threads: {running_threads}')
 
 
 class DeviceError(Exception):
+    """Exception wrapper for device-related errors to provide context about failure source."""
+
     def __init__(self, e: Exception):
         self.base: Exception = e
         self.method = self._attempt_extract_method()

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/ip_parser.py

@@ -1,11 +1,42 @@
+"""
+IP address parsing module for network scanning operations.
+
+This module provides utilities for parsing various IP address formats including:
+- Single IP addresses
+- CIDR notation subnets
+- IP ranges with hyphens (e.g., 192.168.1.1-192.168.1.10)
+- Shorthand IP ranges (e.g., 192.168.1.1-10)
+
+It also includes validation to prevent processing excessively large IP ranges.
+"""
 import ipaddress
-from .errors import SubnetTooLargeError
 import re
 
+from lanscape.libraries.errors import SubnetTooLargeError
+
 MAX_IPS_ALLOWED = 100000
 
 
 def parse_ip_input(ip_input):
+    """
+    Parse various IP address format inputs into a list of IPv4Address objects.
+
+    Supports:
+    - Comma-separated entries
+    - CIDR notation (e.g., 192.168.1.0/24)
+    - IP ranges with a hyphen (e.g., 192.168.1.1-192.168.1.10)
+    - Shorthand IP ranges (e.g., 192.168.1.1-10)
+    - Single IP addresses
+
+    Args:
+        ip_input (str): String containing IP addresses in various formats
+
+    Returns:
+        list: List of IPv4Address objects
+
+    Raises:
+        SubnetTooLargeError: If the number of IPs exceeds MAX_IPS_ALLOWED
+    """
     # Split input on commas for multiple entries
     entries = [entry.strip() for entry in ip_input.split(',')]
     ip_ranges = []
@@ -36,6 +67,15 @@ def parse_ip_input(ip_input):
 
 
 def get_address_count(subnet: str):
+    """
+    Get the number of addresses in an IP subnet.
+
+    Args:
+        subnet (str): Subnet in CIDR notation
+
+    Returns:
+        int: Number of addresses in the subnet, or 0 if invalid
+    """
     try:
         net = ipaddress.IPv4Network(subnet, strict=False)
         return net.num_addresses
@@ -44,6 +84,17 @@ def get_address_count(subnet: str):
 
 
 def parse_ip_range(entry):
+    """
+    Parse an IP range specified with a hyphen (e.g., 192.168.1.1-192.168.1.10).
+
+    Also handles partial end IPs by using the start IP's prefix.
+
+    Args:
+        entry (str): String containing an IP range with a hyphen
+
+    Returns:
+        list: List of IPv4Address objects in the range (inclusive)
+    """
     start_ip, end_ip = entry.split('-')
     start_ip = ipaddress.IPv4Address(start_ip.strip())
 
@@ -56,6 +107,17 @@ def parse_ip_range(entry):
 
 
 def parse_shorthand_ip_range(entry):
+    """
+    Parse a shorthand IP range (e.g., 192.168.1.1-10).
+
+    In this format, only the last octet of the end IP is specified.
+
+    Args:
+        entry (str): String containing a shorthand IP range
+
+    Returns:
+        list: List of IPv4Address objects in the range (inclusive)
+    """
     start_ip, end_part = entry.split('-')
     start_ip = ipaddress.IPv4Address(start_ip.strip())
     end_ip = start_ip.exploded.rsplit('.', 1)[0] + '.' + end_part.strip()
@@ -64,6 +126,16 @@ def parse_shorthand_ip_range(entry):
 
 
 def ip_range_to_list(start_ip, end_ip):
+    """
+    Convert an IP range defined by start and end addresses to a list of addresses.
+
+    Args:
+        start_ip (IPv4Address): The starting IP address
+        end_ip (IPv4Address): The ending IP address
+
+    Yields:
+        IPv4Address: Each IP address in the range (inclusive)
+    """
     # Yield the range of IPs
     for ip_int in range(int(start_ip), int(end_ip) + 1):
         yield ipaddress.IPv4Address(ip_int)

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/logger.py

@@ -1,10 +1,31 @@
+"""
+Logging configuration module for the lanscape application.
+
+This module provides utilities to configure logging for both console and file output,
+with options to control log levels and disable Flask's verbose logging output.
+"""
 import logging
 from logging.handlers import RotatingFileHandler
-import click
 from typing import Optional
 
+import click
+
 
 def configure_logging(loglevel: str, logfile: Optional[str], flask_logging: bool = False) -> None:
+    """
+    Configure the application's logging system.
+
+    Sets up logging with the specified log level and optionally directs output to a file.
+    When a logfile is specified, rotating file handlers are configured to manage log size.
+
+    Args:
+        loglevel (str): Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        logfile (Optional[str]): Path to log file, or None for console-only logging
+        flask_logging (bool): Whether to allow Flask's default logging (defaults to False)
+
+    Raises:
+        ValueError: If an invalid log level is specified
+    """
     numeric_level = getattr(logging, loglevel.upper(), None)
     if not isinstance(numeric_level, int):
         raise ValueError(f'Invalid log level: {loglevel}')
@@ -30,10 +51,17 @@ def configure_logging(loglevel: str, logfile: Optional[str], flask_logging: bool
 
 
 def disable_flask_logging() -> None:
+    """
+    Disable Flask and Werkzeug logging output.
 
+    Overrides click's echo and secho functions to suppress output and
+    sets Werkzeug's logger level to ERROR to reduce log verbosity.
+    """
     def override_click_logging():
+        # pylint: disable=unused-argument
         def secho(text, file=None, nl=None, err=None, color=None, **styles):
             pass
+        # pylint: disable=unused-argument
 
         def echo(text, file=None, nl=None, err=None, color=None, **styles):
             pass

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/mac_lookup.py

@@ -1,3 +1,8 @@
+"""
+MAC address lookup and resolution service.
+This module provides functionality to look up MAC addresses and resolve them
+"""
+
 import re
 import logging
 import platform

{lanscape-1.3.5a1 → lanscape-1.3.5a2}/lanscape/libraries/net_tools.py

@@ -1,3 +1,5 @@
+"""Network tools for scanning and managing devices on a network."""
+
 import logging
 import ipaddress
 import traceback
@@ -29,7 +31,6 @@ class IPAlive(JobStatsMixin):
     caught_errors: List[DeviceError] = []
     _icmp_alive: bool = False
     _arp_alive: bool = False
-    
 
     @job_tracker
     def is_alive(
@@ -99,15 +100,16 @@ class IPAlive(JobStatsMixin):
                 try:
                     if psutil.WINDOWS:
                         cmd = [
-                            "ping", "-n", str(cfg.ping_count), 
+                            "ping", "-n", str(cfg.ping_count),
                             "-w", str(int(cfg.timeout * 1000)), ip
                         ]
                     else:
-                        cmd = ["ping", "-c", str(cfg.ping_count), "-W", str(cfg.timeout), ip]
+                        cmd = ["ping", "-c",
+                               str(cfg.ping_count), "-W", str(cfg.timeout), ip]
 
                     result = subprocess.run(
-                        cmd, stdout=subprocess.PIPE, 
-                        stderr=subprocess.PIPE, 
+                        cmd, stdout=subprocess.PIPE,
+                        stderr=subprocess.PIPE,
                         text=True, check=False
                     )
                     return result.returncode == 0
@@ -245,6 +247,7 @@ class MacSelector:
             self.macs[mac] = self.macs.get(mac, 0) + 1
 
     def clear(self):
+        """Clear the stored MAC addresses."""
         self.macs = {}
 
 
@@ -281,15 +284,15 @@ def get_ip_address(interface: str):
     # Call the appropriate function based on the platform
     if psutil.WINDOWS:
         return windows()
-    else:  # Linux, macOS, and other Unix-like systems
-        return unix_like()
+
+    # Linux, macOS, and other Unix-like systems
+    return unix_like()
 
 
 def get_netmask(interface: str):
     """
     Get the netmask of a network interface.
     """
-
     def unix_like():  # Combined Linux and macOS
         try:
             # pylint: disable=import-outside-toplevel, import-error
@@ -316,8 +319,9 @@ def get_netmask(interface: str):
 
     if psutil.WINDOWS:
         return windows()
-    else:  # Linux, macOS, and other Unix-like systems
-        return unix_like()
+
+    # Linux, macOS, and other Unix-like systems
+    return unix_like()
 
 
 def get_cidr_from_netmask(netmask: str):
@@ -329,71 +333,122 @@ def get_cidr_from_netmask(netmask: str):
     return str(len(binary_str.rstrip('0')))
 
 
+def _find_interface_by_default_gateway_windows():
+    """Find the network interface with the default gateway on Windows."""
+    try:
+        output = subprocess.check_output(
+            "route print 0.0.0.0", shell=True, text=True)
+        return _parse_windows_route_output(output)
+    except Exception as e:
+        log.debug(f"Error finding Windows interface by gateway: {e}")
+    return None
+
+
+def _parse_windows_route_output(output):
+    """Parse the output of Windows route command to extract interface index."""
+    lines = output.strip().split('\n')
+    interface_idx = None
+
+    # First find the interface index from the routing table
+    for line in lines:
+        if '0.0.0.0' in line and 'Gateway' not in line:  # Skip header
+            parts = [p for p in line.split() if p]
+            if len(parts) >= 4:
+                interface_idx = parts[3]
+                break
+
+    # If we found an index, find the corresponding interface name
+    if interface_idx:
+        for iface_name in psutil.net_if_addrs():
+            if str(interface_idx) in iface_name:
+                return iface_name
+
+    return None
+
+
+def _find_interface_by_default_gateway_unix():
+    """Find the network interface with the default gateway on Unix-like systems."""
+    try:
+        cmd = "ip route show default 2>/dev/null || netstat -rn | grep default"
+        output = subprocess.check_output(cmd, shell=True, text=True)
+        return _parse_unix_route_output(output)
+    except Exception as e:
+        log.debug(f"Error finding Unix interface by gateway: {e}")
+    return None
+
+
+def _parse_unix_route_output(output):
+    """Parse the output of Unix route commands to extract interface name."""
+    for line in output.split('\n'):
+        # Parse lines with 'default via ... dev ...'
+        if 'default via' in line and 'dev' in line:
+            return line.split('dev')[1].split()[0]
+
+        # Parse simpler 'default ...' lines
+        if 'default' in line:
+            parts = line.split()
+            if len(parts) > 3:
+                # Interface is usually the last column
+                return parts[-1]
+    return None
+
+
+def _get_candidate_interfaces():
+    """Get a list of candidate network interfaces."""
+    candidates = []
+    for interface, addrs in psutil.net_if_addrs().items():
+        stats = psutil.net_if_stats().get(interface)
+        if not stats or not stats.isup:
+            continue
+
+        ipv4_addrs = [addr for addr in addrs if addr.family == socket.AF_INET]
+        if not ipv4_addrs:
+            continue
+
+        # Skip loopback and common virtual interfaces
+        is_loopback = any(addr.address.startswith('127.')
+                          for addr in ipv4_addrs)
+        if is_loopback:
+            continue
+
+        virtual_names = ['loop', 'vmnet', 'vbox', 'docker', 'virtual', 'veth']
+        is_virtual = any(name in interface.lower() for name in virtual_names)
+        if is_virtual:
+            continue
+
+        candidates.append(interface)
+    return candidates
+
+
 def get_primary_interface():
     """
     Get the primary network interface that is likely handling internet traffic.
     Uses heuristics to identify the most probable interface.
     """
     # Try to find the interface with the default gateway
-    try:
-        if psutil.WINDOWS:
-            # On Windows, parse route print output
-            output = subprocess.check_output(
-                "route print 0.0.0.0", shell=True, text=True)
-            lines = output.strip().split('\n')
-            for line in lines:
-                if '0.0.0.0' in line and 'Gateway' not in line:  # Skip header
-                    parts = [p for p in line.split() if p]
-                    if len(parts) >= 4:
-                        interface_idx = parts[3]
-                        # Find interface name in the output
-                        for iface_name, addrs in psutil.net_if_addrs().items():
-                            if str(interface_idx) in iface_name:
-                                return iface_name
-        else:
-            # Linux/Unix/Mac - use ip route or netstat
-            try:
-                output = subprocess.check_output(
-                    "ip route show default 2>/dev/null || netstat -rn | grep default", shell=True, text=True)
-                for line in output.split('\n'):
-                    if 'default via' in line and 'dev' in line:
-                        return line.split('dev')[1].split()[0]
-                    elif 'default' in line:
-                        parts = line.split()
-                        if len(parts) > 3:
-                            # Interface is usually the last column
-                            return parts[-1]
-            except (subprocess.SubprocessError, IndexError, FileNotFoundError):
-                pass
-    except Exception as e:
-        log.debug(f"Error determining primary interface: {e}")
+    if psutil.WINDOWS:
+        interface = _find_interface_by_default_gateway_windows()
+        if interface:
+            return interface
+    else:
+        interface = _find_interface_by_default_gateway_unix()
+        if interface:
+            return interface
 
     # Fallback: Identify likely candidates based on heuristics
-    candidates = []
-
-    for interface, addrs in psutil.net_if_addrs().items():
-        stats = psutil.net_if_stats().get(interface)
-        if stats and stats.isup:
-            ipv4_addrs = [
-                addr for addr in addrs if addr.family == socket.AF_INET]
-            if ipv4_addrs:
-                # Skip loopback and common virtual interfaces
-                is_loopback = any(addr.address.startswith('127.')
-                                  for addr in ipv4_addrs)
-                is_virtual = any(name in interface.lower() for name in
-                                 ['loop', 'vmnet', 'vbox', 'docker', 'virtual', 'veth'])
-
-                if not is_loopback and not is_virtual:
-                    candidates.append(interface)
+    candidates = _get_candidate_interfaces()
+    if not candidates:
+        return None
 
     # Prioritize interfaces with names typically used for physical connections
-    for prefix in ['eth', 'en', 'wlan', 'wifi', 'wl', 'wi']:
+    physical_prefixes = ['eth', 'en', 'wlan', 'wifi', 'wl', 'wi']
+    for prefix in physical_prefixes:
         for interface in candidates:
             if interface.lower().startswith(prefix):
                 return interface
 
-    # Otherwise return the first candidate or None
-    return candidates[0] if candidates else None
+    # Otherwise return the first candidate
+    return candidates[0]
 
 
 def get_host_ip_mask(ip_with_cidr: str):
@@ -456,13 +511,16 @@ def network_from_snicaddr(snicaddr: psutil._common.snicaddr) -> str:
     """
     if not snicaddr.address or not snicaddr.netmask:
         return None
-    elif snicaddr.family == socket.AF_INET:
+
+    if snicaddr.family == socket.AF_INET:
         addr = f"{snicaddr.address}/{get_cidr_from_netmask(snicaddr.netmask)}"
-    elif snicaddr.family == socket.AF_INET6:
+        return get_host_ip_mask(addr)
+
+    if snicaddr.family == socket.AF_INET6:
         addr = f"{snicaddr.address}/{snicaddr.netmask}"
-    else:
-        return f"{snicaddr.address}"
-    return get_host_ip_mask(addr)
+        return get_host_ip_mask(addr)
+
+    return f"{snicaddr.address}"
 
 
 def smart_select_primary_subnet(subnets: List[dict] = None) -> str:

lanscape-1.3.5a2/lanscape/libraries/port_manager.py

@@ -0,0 +1,150 @@
+"""
+Port Manager module for managing port list configurations.
+
+This module provides functionality to create, read, update, and delete port lists
+that are stored as JSON files. Each port list contains port numbers and their
+associated services. The module handles validation of port data and provides
+methods for working with port list configurations.
+"""
+
+import json
+from typing import List
+from pathlib import Path
+from .app_scope import ResourceManager
+
+PORT_DIR = 'ports'
+
+
+class PortManager:
+    """
+    Manager class for port list operations.
+
+    Handles the creation, retrieval, updating, and deletion of port lists.
+    Port lists are stored as JSON files with port numbers as keys and
+    service names as values.
+    """
+
+    def __init__(self):
+        """
+        Initialize the PortManager.
+
+        Creates the ports directory if it doesn't exist and initializes
+        the ResourceManager for file operations.
+        """
+        Path(PORT_DIR).mkdir(parents=True, exist_ok=True)
+        self.rm = ResourceManager(PORT_DIR)
+
+    def get_port_lists(self) -> List[str]:
+        """
+        Get a list of all available port list names.
+
+        Returns:
+            List[str]: Names of all available port lists (without .json extension)
+        """
+        return [f.replace('.json', '') for f in self.rm.list() if f.endswith('.json')]
+
+    def get_port_list(self, port_list: str) -> dict:
+        """
+        Retrieve a port list by name.
+
+        Args:
+            port_list (str): The name of the port list to retrieve
+
+        Returns:
+            dict: A dictionary of port numbers to service names
+
+        Raises:
+            ValueError: If the specified port list does not exist
+        """
+        if port_list not in self.get_port_lists():
+            msg = f"Port list '{port_list}' does not exist. "
+            msg += f"Available port lists: {self.get_port_lists()}"
+            raise ValueError(msg)
+
+        data = json.loads(self.rm.get(f'{port_list}.json'))
+
+        return data if self.validate_port_data(data) else None
+
+    def create_port_list(self, port_list: str, data: dict) -> bool:
+        """
+        Create a new port list.
+
+        Args:
+            port_list (str): Name for the new port list
+            data (dict): Dictionary mapping port numbers to service names
+
+        Returns:
+            bool: True if creation was successful, False otherwise
+        """
+        if port_list in self.get_port_lists():
+            return False
+        if not self.validate_port_data(data):
+            return False
+
+        self.rm.create(f'{port_list}.json', json.dumps(data, indent=2))
+
+        return True
+
+    def update_port_list(self, port_list: str, data: dict) -> bool:
+        """
+        Update an existing port list.
+
+        Args:
+            port_list (str): Name of the port list to update
+            data (dict): New dictionary mapping port numbers to service names
+
+        Returns:
+            bool: True if update was successful, False otherwise
+        """
+        if port_list not in self.get_port_lists():
+            return False
+        if not self.validate_port_data(data):
+            return False
+
+        self.rm.update(f'{port_list}.json', json.dumps(data, indent=2))
+
+        return True
+
+    def delete_port_list(self, port_list: str) -> bool:
+        """
+        Delete a port list.
+
+        Args:
+            port_list (str): Name of the port list to delete
+
+        Returns:
+            bool: True if deletion was successful, False otherwise
+        """
+        if port_list not in self.get_port_lists():
+            return False
+
+        self.rm.delete(f'{port_list}.json')
+
+        return True
+
+    def validate_port_data(self, port_data: dict) -> bool:
+        """
+        Validate port data structure and content.
+
+        Ensures that:
+        - Keys can be converted to integers
+        - Values are strings
+        - Port numbers are within valid range (0-65535)
+
+        Args:
+            port_data (dict): Dictionary mapping port numbers to service names
+
+        Returns:
+            bool: True if data is valid, False otherwise
+        """
+        try:
+            for port, service in port_data.items():
+                port = int(port)  # throws if not int
+                if not isinstance(service, str):
+                    return False
+
+                if not 0 <= port <= 65535:
+                    return False
+            return True
+        except BaseException:
+            return False