lanscape 1.3.4__py3-none-any.whl → 1.3.5a2__py3-none-any.whl

lanscape/libraries/runtime_args.py

@@ -1,3 +1,5 @@
+"""Runtime argument handler for LANscape as module"""
+
 from dataclasses import dataclass, fields
 import argparse
 from typing import Any, Dict, Optional
@@ -5,6 +7,7 @@ from typing import Any, Dict, Optional
 
 @dataclass
 class RuntimeArgs:
+    """Class representing runtime arguments for the application."""
     reloader: bool = False
     port: int = 5001
     logfile: Optional[str] = None
@@ -14,6 +17,9 @@ class RuntimeArgs:
 
 
 def parse_args() -> RuntimeArgs:
+    """
+    Parse command line arguments and return a RuntimeArgs instance.
+    """
     parser = argparse.ArgumentParser(description='LANscape')
 
     parser.add_argument('--reloader', action='store_true',
@@ -27,6 +33,8 @@ def parse_args() -> RuntimeArgs:
                         help='Enable flask logging (disables click output)')
     parser.add_argument('--persistent', action='store_true',
                         help='Don\'t exit after browser is closed')
+    parser.add_argument('--debug', action='store_true',
+                        help='Shorthand debug mode (equivalent to "--loglevel DEBUG --reloader")')
 
     # Parse the arguments
     args = parser.parse_args()
@@ -37,6 +45,10 @@ def parse_args() -> RuntimeArgs:
     field_names = {field.name for field in fields(
         RuntimeArgs)}  # Get dataclass field names
 
+    if args.debug:
+        args_dict['loglevel'] = 'DEBUG'
+        args_dict['reloader'] = True
+
     # Only pass arguments that exist in the Args dataclass
     filtered_args = {name: args_dict[name]
                      for name in field_names if name in args_dict}

lanscape/libraries/scan_config.py

@@ -1,13 +1,26 @@
-from typing import List
+"""
+Configuration module for network scanning operations.
+Provides classes and utilities to configure different types of network scans
+including ping scans, ARP scans, and port scanning.
+"""
+
+from typing import List, Dict
 import ipaddress
-from pydantic import BaseModel, Field
 from enum import Enum
 
+from pydantic import BaseModel, Field
+
 from lanscape.libraries.port_manager import PortManager
 from lanscape.libraries.ip_parser import parse_ip_input
 
 
 class PingConfig(BaseModel):
+    """
+    Configuration settings for ICMP ping-based network scanning.
+
+    Controls parameters such as the number of ping attempts, count per ping,
+    timeout values, and retry delays to optimize ping scanning behavior.
+    """
     attempts: int = 2
     ping_count: int = 1
     timeout: float = 1.0
@@ -15,9 +28,24 @@ class PingConfig(BaseModel):
 
     @classmethod
     def from_dict(cls, data: dict) -> 'PingConfig':
+        """
+        Create a PingConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing PingConfig parameters
+
+        Returns:
+            A new PingConfig instance with the provided settings
+        """
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
+        """
+        Convert the PingConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the PingConfig
+        """
         return self.model_dump()
 
     def __str__(self):
@@ -38,9 +66,24 @@ class ArpConfig(BaseModel):
 
     @classmethod
     def from_dict(cls, data: dict) -> 'ArpConfig':
+        """
+        Create an ArpConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing ArpConfig parameters
+
+        Returns:
+            A new ArpConfig instance with the provided settings
+        """
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
+        """
+        Convert the ArpConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the ArpConfig
+        """
         return self.model_dump()
 
     def __str__(self):
@@ -48,12 +91,25 @@ class ArpConfig(BaseModel):
 
 
 class ScanType(Enum):
+    """
+    Enumeration of supported network scan types.
+
+    PING: Uses ICMP echo requests to determine if hosts are alive
+    ARP: Uses Address Resolution Protocol to discover hosts on the local network
+    BOTH: Uses both PING and ARP methods for maximum coverage
+    """
     PING = 'ping'
     ARP = 'arp'
     BOTH = 'both'
 
 
 class ScanConfig(BaseModel):
+    """
+    Main configuration class for network scanning operations.
+
+    Contains settings for subnet targets, port ranges, thread counts,
+    scan tasks to perform, and configurations for different scan methods.
+    """
     subnet: str
     port_list: str
     t_multiplier: float = 1.0
@@ -70,11 +126,31 @@ class ScanConfig(BaseModel):
     ping_config: PingConfig = Field(default_factory=PingConfig)
     arp_config: ArpConfig = Field(default_factory=ArpConfig)
 
-    def t_cnt(self, id: str) -> int:
-        return int(int(getattr(self, f't_cnt_{id}')) * float(self.t_multiplier))
+    def t_cnt(self, thread_id: str) -> int:
+        """
+        Calculate thread count for a specific operation based on multiplier.
+
+        Args:
+            thread_id: String identifier for the thread type (e.g., 'port_scan')
+
+        Returns:
+            Calculated thread count for the specified operation
+        """
+        return int(int(getattr(self, f't_cnt_{thread_id}')) * float(self.t_multiplier))
 
     @classmethod
     def from_dict(cls, data: dict) -> 'ScanConfig':
+        """
+        Create a ScanConfig instance from a dictionary.
+
+        Handles special cases like converting string enum values to proper Enum types.
+
+        Args:
+            data: Dictionary containing ScanConfig parameters
+
+        Returns:
+            A new ScanConfig instance with the provided settings
+        """
         # Handle special cases before validation
         if isinstance(data.get('lookup_type'), str):
             data['lookup_type'] = ScanType[data['lookup_type'].upper()]
@@ -82,12 +158,34 @@ class ScanConfig(BaseModel):
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
-        return self.model_dump()
+        """
+        Convert the ScanConfig instance to a dictionary.
+
+        Handles special cases like converting Enum values to strings.
+
+        Returns:
+            Dictionary representation of the ScanConfig
+        """
+        dump = self.model_dump()
+        dump['lookup_type'] = self.lookup_type.value
+        return dump
 
     def get_ports(self) -> List[int]:
+        """
+        Get the list of ports to scan based on the configured port list name.
+
+        Returns:
+            List of port numbers to scan
+        """
         return PortManager().get_port_list(self.port_list).keys()
 
     def parse_subnet(self) -> List[ipaddress.IPv4Network]:
+        """
+        Parse the configured subnet string into IPv4Network objects.
+
+        Returns:
+            List of IPv4Network objects representing the target networks
+        """
         return parse_ip_input(self.subnet)
 
     def __str__(self):
@@ -95,3 +193,48 @@ class ScanConfig(BaseModel):
         b = f'ports={self.port_list}'
         c = f'scan_type={self.lookup_type.value}'
         return f'ScanConfig({a}, {b}, {c})'
+
+
+DEFAULT_CONFIGS: Dict[str, ScanConfig] = {
+    'balanced': ScanConfig(subnet='', port_list='medium'),
+    'accurate': ScanConfig(
+        subnet='',
+        port_list='large',
+        t_cnt_port_scan=5,
+        t_cnt_port_test=64,
+        t_cnt_isalive=64,
+        task_scan_ports=True,
+        task_scan_port_services=False,
+        lookup_type=ScanType.BOTH,
+        arp_config=ArpConfig(
+            attempts=3,
+            timeout=2.5
+        ),
+        ping_config=PingConfig(
+            attempts=3,
+            ping_count=2,
+            timeout=1.5,
+            retry_delay=0.5
+        )
+    ),
+    'fast': ScanConfig(
+        subnet='',
+        port_list='small',
+        t_cnt_port_scan=20,
+        t_cnt_port_test=256,
+        t_cnt_isalive=512,
+        task_scan_ports=True,
+        task_scan_port_services=False,
+        lookup_type=ScanType.BOTH,
+        arp_config=ArpConfig(
+            attempts=1,
+            timeout=1.0
+        ),
+        ping_config=PingConfig(
+            attempts=1,
+            ping_count=1,
+            timeout=0.5,
+            retry_delay=0.25
+        )
+    )
+}

lanscape/libraries/service_scan.py

@@ -1,7 +1,8 @@
+"""Service scanning module for identifying services running on network ports."""
 import asyncio
 import logging
 import traceback
-from .app_scope import ResourceManager
+from lanscape.libraries.app_scope import ResourceManager
 
 log = logging.getLogger('ServiceScan')
 SERVICES = ResourceManager('services').get_jsonc('definitions.jsonc')
@@ -24,8 +25,7 @@ def scan_service(ip: str, port: int, timeout=10) -> str:
             reader, writer = await asyncio.wait_for(asyncio.open_connection(ip, port), timeout=5)
 
             # Send a probe appropriate for common services
-            probe = "GET / HTTP/1.1\r\nHost: {}\r\n\r\n".format(
-                ip).encode("utf-8")
+            probe = f"GET / HTTP/1.1\r\nHost: {ip}\r\n\r\n".encode("utf-8")
             writer.write(probe)
             await writer.drain()
 

lanscape/libraries/subnet_scan.py

@@ -1,5 +1,10 @@
-from .scan_config import ScanConfig
-from .decorators import job_tracker, terminator, JobStatsMixin
+"""
+Network subnet scanning module for LANscape.
+Provides classes for performing network discovery, device scanning, and port scanning.
+Handles scan management, result tracking, and scan termination.
+"""
+
+# Standard library imports
 import os
 import json
 import uuid
@@ -7,33 +12,49 @@ import logging
 import ipaddress
 import traceback
 import threading
-from time import time
-from time import sleep
+from time import time, sleep
 from typing import List, Union
-from tabulate import tabulate
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
-from .net_tools import Device, is_arp_supported
-from .errors import SubnetScanTerminationFailure
+# Third-party imports
+from tabulate import tabulate
+
+# Local imports
+from lanscape.libraries.scan_config import ScanConfig
+from lanscape.libraries.decorators import job_tracker, terminator, JobStatsMixin
+from lanscape.libraries.net_tools import Device, is_arp_supported
+from lanscape.libraries.errors import SubnetScanTerminationFailure
 
 
 class SubnetScanner(JobStatsMixin):
+    """
+    Scans a subnet for devices and open ports.
+
+    Manages the scanning process including device discovery and port scanning.
+    Tracks scan progress and provides mechanisms for controlled termination.
+    """
+
     def __init__(
         self,
         config: ScanConfig
     ):
+        # Config and network properties
         self.cfg = config
         self.subnet = config.parse_subnet()
         self.ports: List[int] = config.get_ports()
-        self.running = False
         self.subnet_str = config.subnet
 
+        # Status properties
+        self.running = False
         self.uid = str(uuid.uuid4())
         self.results = ScannerResults(self)
         self.log: logging.Logger = logging.getLogger('SubnetScanner')
+
+        # Initial logging
         if not is_arp_supported():
             self.log.warning(
-                'ARP is not supported with the active runtime context. Device discovery will be limited to ping responses.')
+                'ARP is not supported with the active runtime context. '
+                'Device discovery will be limited to ping responses.')
         self.log.debug(f'Instantiated with uid: {self.uid}')
         self.log.debug(
             f'Port Count: {len(self.ports)} | Device Count: {len(self.subnet)}')
@@ -68,16 +89,36 @@ class SubnetScanner(JobStatsMixin):
         return self.results
 
     def terminate(self):
+        """
+        Terminate the scan operation.
+
+        Attempts a graceful shutdown of all scan operations and waits for running
+        tasks to complete. Raises an exception if termination takes too long.
+
+        Returns:
+            bool: True if terminated successfully
+
+        Raises:
+            SubnetScanTerminationFailure: If the scan cannot be terminated within the timeout
+        """
         self.running = False
         self._set_stage('terminating')
-        for i in range(20):
-            if not len(self.job_stats.running.keys()):
+        for _ in range(20):
+            if not self.job_stats.running:
                 self._set_stage('terminated')
                 return True
             sleep(.5)
         raise SubnetScanTerminationFailure(self.job_stats.running)
 
     def calc_percent_complete(self) -> int:  # 0 - 100
+        """
+        Calculate the percentage completion of the scan.
+
+        Uses scan statistics and job timing information to estimate progress.
+
+        Returns:
+            int: Completion percentage (0-100)
+        """
         if not self.running:
             return 100
 
@@ -85,7 +126,7 @@ class SubnetScanner(JobStatsMixin):
         avg_host_detail_sec = self.job_stats.timing.get(
             '_get_host_details', 4.5)
         # assume 10% alive percentage if the scan just started
-        if len(self.results.devices) and (self.results.devices_scanned):
+        if self.results.devices and self.results.devices_scanned:
             est_subnet_alive_percent = (
                 # avoid div 0
                 len(self.results.devices)) / (self.results.devices_scanned)
@@ -213,38 +254,65 @@ class SubnetScanner(JobStatsMixin):
 
 
 class ScannerResults:
+    """
+    Stores and manages the results of a subnet scan.
+
+    Tracks devices found, scan statistics, and provides export functionality
+    for scan results. Also handles runtime calculation and progress tracking.
+    """
+
     def __init__(self, scan: SubnetScanner):
+        # Parent reference and identifiers
         self.scan = scan
         self.port_list: str = scan.cfg.port_list
         self.subnet: str = scan.subnet_str
         self.uid = scan.uid
 
+        # Scan statistics
         self.devices_total: int = len(list(scan.subnet))
         self.devices_scanned: int = 0
         self.devices: List[Device] = []
+        self.devices_alive = 0
 
+        # Status tracking
         self.errors: List[str] = []
         self.running: bool = False
         self.start_time: float = time()
         self.end_time: int = None
         self.stage = 'instantiated'
+        self.run_time = 0
 
+        # Logging
         self.log = logging.getLogger('ScannerResults')
         self.log.debug(f'Instantiated Logger For Scan: {self.scan.uid}')
 
     def scanned(self):
+        """
+        Increment the count of scanned devices.
+        """
         self.devices_scanned += 1
 
     def get_runtime(self):
+        """
+        Calculate the runtime of the scan in seconds.
+
+        Returns:
+            int: Runtime in seconds
+        """
         if self.scan.running:
             return int(time() - self.start_time)
         return int(self.end_time - self.start_time)
 
     def export(self, out_type=dict) -> Union[str, dict]:
         """
-            Returns json representation of the scan
-        """
+        Export scan results in the specified format.
 
+        Args:
+            out_type: The output type (dict or str)
+
+        Returns:
+            Union[str, dict]: Scan results in the specified format
+        """
         self.running = self.scan.running
         self.run_time = int(round(time() - self.start_time, 0))
         self.devices_alive = len(self.devices)
@@ -255,9 +323,9 @@ class ScannerResults:
         out['cfg'] = vars(self.scan.cfg)
 
         devices: List[Device] = out.pop('devices')
-        sortedDevices = sorted(
+        sorted_devices = sorted(
             devices, key=lambda obj: ipaddress.IPv4Address(obj.ip))
-        out['devices'] = [device.dict() for device in sortedDevices]
+        out['devices'] = [device.dict() for device in sorted_devices]
 
         if out_type == str:
             return json.dumps(out, default=str, indent=2)
@@ -304,6 +372,15 @@ class ScanManager:
             self.log = logging.getLogger('ScanManager')
 
     def new_scan(self, config: ScanConfig) -> SubnetScanner:
+        """
+        Create and start a new scan with the given configuration.
+
+        Args:
+            config: The scan configuration
+
+        Returns:
+            SubnetScanner: The newly created scan instance
+        """
         scan = SubnetScanner(config)
         self._start(scan)
         self.log.info(f'Scan started - {config}')
@@ -317,6 +394,7 @@ class ScanManager:
         for scan in self.scans:
             if scan.uid == scan_id:
                 return scan
+        return None  # Explicitly return None for consistency
 
     def terminate_scans(self):
         """
@@ -327,12 +405,22 @@ class ScanManager:
                 scan.terminate()
 
     def wait_until_complete(self, scan_id: str) -> SubnetScanner:
+        """Wait for a scan to complete."""
         scan = self.get_scan(scan_id)
         while scan.running:
             sleep(.5)
         return scan
 
     def _start(self, scan: SubnetScanner):
+        """
+        Start a scan in a separate thread.
+
+        Args:
+            scan: The scan to start
+
+        Returns:
+            Thread: The thread running the scan
+        """
         t = threading.Thread(target=scan.start)
         t.start()
         return t

lanscape/libraries/version_manager.py

@@ -1,9 +1,16 @@
+"""
+Version management module for LANscape.
+Handles version checking, update detection, and retrieving package information
+from both local installation and PyPI repository.
+"""
+
 import logging
-import requests
 import traceback
 from importlib.metadata import version, PackageNotFoundError
 from random import randint
 
+import requests
+
 from .app_scope import is_local_run
 
 log = logging.getLogger('VersionManager')
@@ -11,10 +18,23 @@ log = logging.getLogger('VersionManager')
 PACKAGE = 'lanscape'
 LOCAL_VERSION = '0.0.0'
 
-latest = None  # used to 'remember' pypi version each runtime
+# Used to cache PyPI version during runtime
+LATEST_VERSION = None
 
 
 def is_update_available(package=PACKAGE) -> bool:
+    """
+    Check if an update is available for the package.
+
+    Compares the installed version with the latest version available on PyPI.
+    Ignores pre-release versions (alpha/beta) and local development installs.
+
+    Args:
+        package: The package name to check for updates
+
+    Returns:
+        Boolean indicating if an update is available
+    """
     installed = get_installed_version(package)
     available = lookup_latest_version(package)
 
@@ -30,23 +50,46 @@ def is_update_available(package=PACKAGE) -> bool:
 
 
 def lookup_latest_version(package=PACKAGE):
+    """
+    Retrieve the latest version of the package from PyPI.
+
+    Caches the result for subsequent calls during the same runtime.
+
+    Args:
+        package: The package name to lookup
+
+    Returns:
+        The latest version string from PyPI or None if retrieval fails
+    """
     # Fetch the latest version from PyPI
-    global latest
-    if not latest:
+    global LATEST_VERSION  # pylint: disable=global-statement
+    if not LATEST_VERSION:
         no_cache = f'?cachebust={randint(0, 6969)}'
         url = f"https://pypi.org/pypi/{package}/json{no_cache}"
         try:
             response = requests.get(url, timeout=5)
             response.raise_for_status()  # Raise an exception for HTTP errors
-            latest = response.json()['info']['version']
-            log.debug(f'Latest pypi version: {latest}')
+            LATEST_VERSION = response.json()['info']['version']
+            log.debug(f'Latest pypi version: {LATEST_VERSION}')
         except BaseException:
             log.debug(traceback.format_exc())
             log.warning('Unable to fetch package version from PyPi')
-    return latest
+    return LATEST_VERSION
 
 
 def get_installed_version(package=PACKAGE):
+    """
+    Get the installed version of the package.
+
+    Returns the current installed version or a default local version
+    if running in development mode or if the package is not found.
+
+    Args:
+        package: The package name to check
+
+    Returns:
+        The installed version string or LOCAL_VERSION for local development
+    """
     if not is_local_run():
         try:
             return version(package)