lanscape 1.3.5a1__py3-none-any.whl → 1.3.6a1__py3-none-any.whl

lanscape/__init__.py

@@ -3,10 +3,18 @@ Local network scanner
 """
 from lanscape.libraries.subnet_scan import (
     SubnetScanner,
-    ScanConfig,
     ScanManager
 )
 
+from lanscape.libraries.scan_config import (
+    ScanConfig,
+    ArpConfig,
+    PingConfig,
+    PokeConfig,
+    ArpCacheConfig,
+    ScanType
+)
+
 from lanscape.libraries.port_manager import PortManager
 
 from lanscape.libraries import net_tools

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/libraries/decorators.py

@@ -18,9 +18,26 @@ 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))
+
+    _instance = None
+
+    def __init__(self):
+        # Only initialize once
+        if not hasattr(self, "running"):
+            self.running = defaultdict(int)
+            self.finished = defaultdict(int)
+            self.timing = defaultdict(float)
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super(JobStats, cls).__new__(cls)
+        return cls._instance
 
     def __str__(self):
         """Return a formatted string representation of the job statistics."""
@@ -50,14 +67,13 @@ class JobStatsMixin:  # pylint: disable=too-few-public-methods
     @property
     def job_stats(self):
         """Return the shared JobStats instance."""
-        if JobStatsMixin._job_stats is None:
-            JobStatsMixin._job_stats = JobStats()
-        return JobStatsMixin._job_stats
+        return JobStats()
 
 
 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:
         """
@@ -77,7 +93,7 @@ def job_tracker(func):
     def wrapper(*args, **kwargs):
         """Wrap the function to update job statistics before and after execution."""
         class_instance = args[0]
-        job_stats = class_instance.job_stats
+        job_stats = JobStats()
         fxn = get_fxn_src_name(
             func,
             class_instance
@@ -112,7 +128,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/libraries/device_alive.py

@@ -0,0 +1,227 @@
+"""
+Handles device alive checks using various methods.
+"""
+
+import re
+import socket
+import subprocess
+import time
+import random
+from typing import List
+import psutil
+
+from scapy.sendrecv import srp
+from scapy.layers.l2 import ARP, Ether
+from icmplib import ping
+
+from lanscape.libraries.net_tools import Device
+from lanscape.libraries.scan_config import (
+    ScanConfig, ScanType, PingConfig,
+    ArpConfig, PokeConfig, ArpCacheConfig
+)
+from lanscape.libraries.decorators import timeout_enforcer, job_tracker
+
+
+def is_device_alive(device: Device, scan_config: ScanConfig) -> bool:
+    """
+    Check if a device is alive based on the configured scan type.
+
+    Args:
+        device (Device): The device to check.
+        scan_config (ScanConfig): The configuration for the scan.
+
+    Returns:
+        bool: True if the device is alive, False otherwise.
+    """
+    methods = scan_config.lookup_type
+
+    if ScanType.ICMP in methods:
+        IcmpLookup.execute(device, scan_config.ping_config)
+
+    if ScanType.ARP_LOOKUP in methods and not device.alive:
+        ArpLookup.execute(device, scan_config.arp_config)
+
+    if ScanType.ICMP_THEN_ARP in methods and not device.alive:
+        IcmpLookup.execute(device, scan_config.ping_config)
+        ArpCacheLookup.execute(device, scan_config.arp_cache_config)
+
+    if ScanType.POKE_THEN_ARP in methods and not device.alive:
+        Poker.execute(device, scan_config.poke_config)
+        ArpCacheLookup.execute(device, scan_config.arp_cache_config)
+
+    return device.alive is True
+
+
+class IcmpLookup():
+    """Class to handle ICMP ping lookups for device presence.
+
+    Raises:
+        NotImplementedError: If the platform is not supported.
+
+    Returns:
+        bool: True if the device is reachable via ICMP, False otherwise.
+    """
+    @classmethod
+    @job_tracker
+    def execute(cls, device: Device, cfg: PingConfig) -> bool:
+        """Perform an ICMP ping lookup for the specified device.
+
+        Args:
+            device (Device): The device to look up.
+            cfg (PingConfig): The configuration for the scan.
+
+        Returns:
+            bool: True if the device is reachable via ICMP, False otherwise.
+        """
+        # Perform up to cfg.attempts rounds of ping(count=cfg.ping_count)
+        for _ in range(cfg.attempts):
+            result = ping(
+                device.ip,
+                count=cfg.ping_count,
+                interval=cfg.retry_delay,
+                timeout=cfg.timeout,
+                privileged=psutil.WINDOWS  # Use privileged mode on Windows
+            )
+            if result.is_alive:
+                device.alive = True
+                break
+        return device.alive is True
+
+
+class ArpCacheLookup():
+    """
+    Class to handle ARP cache lookups for device presence.
+    """
+
+    @classmethod
+    @job_tracker
+    def execute(cls, device: Device, cfg: ArpCacheConfig) -> bool:
+        """
+        Perform an ARP cache lookup for the specified device.
+
+        Args:
+            device (Device): The device to look up.
+
+        Returns:
+            bool: True if the device is found in the ARP cache, False otherwise.
+        """
+
+        command = cls._get_platform_arp_command() + [device.ip]
+
+        for _ in range(cfg.attempts):
+            time.sleep(cfg.wait_before)
+            output = subprocess.check_output(command).decode()
+            macs = cls._extract_mac_address(output)
+            if macs:
+                device.macs = macs
+                device.alive = True
+                break
+
+        return device.alive is True
+
+    @classmethod
+    def _get_platform_arp_command(cls) -> List[str]:
+        """
+        Get the ARP command to execute based on the platform.
+
+        Returns:
+            list[str]: The ARP command to execute.
+        """
+        if psutil.WINDOWS:
+            return ['arp', '-a']
+        if psutil.LINUX:
+            return ['arp', '-n']
+        if psutil.MACOS:
+            return ['arp', '-n']
+
+        raise NotImplementedError("Unsupported platform")
+
+    @classmethod
+    def _extract_mac_address(cls, arp_resp: str) -> List[str]:
+        """
+        Extract MAC addresses from ARP output.
+
+        Args:
+            arp_resp (str): The ARP command output.
+
+        Returns:
+            List[str]: A list of extracted MAC addresses (may be empty).
+        """
+        arp_resp = arp_resp.replace('-', ':')
+        return re.findall(r'..:..:..:..:..:..', arp_resp)
+
+
+class ArpLookup():
+    """
+    Class to handle ARP lookups for device presence.
+    NOTE: This lookup method requires elevated privileges to access the ARP cache.
+
+
+    [Arp Lookup Requirements](/support/arp-issues.md)
+    """
+
+    @classmethod
+    @job_tracker
+    def execute(cls, device: Device, cfg: ArpConfig) -> bool:
+        """
+        Perform an ARP lookup for the specified device.
+
+        Args:
+            device (Device): The device to look up.
+
+        Returns:
+            bool: True if the device is found via ARP, False otherwise.
+        """
+        enforcer_timeout = cfg.timeout * 2
+
+        @timeout_enforcer(enforcer_timeout, raise_on_timeout=True)
+        def do_arp_lookup():
+            arp_request = ARP(pdst=device.ip)
+            broadcast = Ether(dst="ff:ff:ff:ff:ff:ff")
+            packet = broadcast / arp_request
+
+            answered, _ = srp(packet, timeout=cfg.timeout, verbose=False)
+            alive = any(resp.psrc == device.ip for _, resp in answered)
+            macs = []
+            if alive:
+                macs = [resp.hwsrc for _, resp in answered if resp.psrc == device.ip]
+            return alive, macs
+
+        alive, macs = do_arp_lookup()
+        if alive:
+            device.alive = True
+            device.macs = macs
+
+        return device.alive is True
+
+
+class Poker():
+    """
+    Class to handle Poking the device to populate the ARP cache.
+    """
+
+    @classmethod
+    @job_tracker
+    def execute(cls, device: Device, cfg: PokeConfig):
+        """
+        Perform a Poke for the specified device.
+        Note: the purpose of this is to simply populate the arp cache.
+
+        Args:
+            device (Device): The device to look up.
+            cfg (PokeConfig): The configuration for the Poke lookup.
+
+        Returns:
+            None: used to populate the arp cache
+        """
+        enforcer_timeout = cfg.timeout * cfg.attempts * 2
+
+        @timeout_enforcer(enforcer_timeout, raise_on_timeout=True)
+        def do_poke():
+            for _ in range(cfg.attempts):
+                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                sock.settimeout(cfg.timeout)
+                sock.connect_ex((device.ip, random.randint(1024, 65535)))  # port shouldn't matter
+                sock.close()
+
+        do_poke()

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/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/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/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