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

lanscape/libraries/scan_config.py

@@ -1,14 +1,27 @@
+"""
+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.
+"""
+
+import os
 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
@@ -16,9 +29,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):
@@ -39,64 +67,186 @@ 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):
         return f'ArpCfg(timeout={self.timeout}, attempts={self.attempts})'
 
 
+class ArpCacheConfig(BaseModel):
+    """Config for fetching from ARP cache"""
+    attempts: int = 1
+    wait_before: float = 0.2
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'ArpCacheConfig':
+        """
+        Create an ArpCacheConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing ArpCacheConfig parameters
+
+        Returns:
+            A new ArpCacheConfig instance with the provided settings
+        """
+        return cls.model_validate(data)
+
+    def to_dict(self) -> dict:
+        """
+        Convert the ArpCacheConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the ArpCacheConfig
+        """
+        return self.model_dump()
+
+    def __str__(self):
+        return f'ArpCacheCfg(wait_before={self.wait_before}, attempts={self.attempts})'
+
+
+class PokeConfig(BaseModel):
+    """
+    Poking essentially involves sending a TCP packet to a specific port on a device
+    to elicit a response. Not so much expecting a response, but it should at least
+    trigger an ARP request.
+    """
+    attempts: int = 1
+    timeout: float = 2.0
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'PokeConfig':
+        """
+        Create a PokeConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing PokeConfig parameters
+
+        Returns:
+            A new PokeConfig instance with the provided settings
+        """
+        return cls.model_validate(data)
+
+    def to_dict(self) -> dict:
+        """
+        Convert the PokeConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the PokeConfig
+        """
+        return self.model_dump()
+
+
 class ScanType(Enum):
-    PING = 'ping'
-    ARP = 'arp'
-    BOTH = 'both'
+    """
+    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
+
+    """
+    ICMP = 'ICMP'
+    ARP_LOOKUP = 'ARP_LOOKUP'
+    POKE_THEN_ARP = 'POKE_THEN_ARP'
+    ICMP_THEN_ARP = 'ICMP_THEN_ARP'
 
 
 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
-    t_cnt_port_scan: int = 10
-    t_cnt_port_test: int = 128
-    t_cnt_isalive: int = 256
+    t_cnt_port_scan: int = os.cpu_count()
+    t_cnt_port_test: int = os.cpu_count() * 4
+    t_cnt_isalive: int = os.cpu_count() * 6
 
     task_scan_ports: bool = True
     # below wont run if above false
     task_scan_port_services: bool = False  # disabling until more stable
 
-    lookup_type: ScanType = ScanType.BOTH
+    lookup_type: List[ScanType] = [ScanType.ICMP_THEN_ARP]
 
     ping_config: PingConfig = Field(default_factory=PingConfig)
     arp_config: ArpConfig = Field(default_factory=ArpConfig)
+    poke_config: PokeConfig = Field(default_factory=PokeConfig)
+    arp_cache_config: ArpCacheConfig = Field(default_factory=ArpCacheConfig)
+
+    def t_cnt(self, thread_id: str) -> int:
+        """
+        Calculate thread count for a specific operation based on multiplier.
 
-    def t_cnt(self, id: str) -> int:
-        return int(int(getattr(self, f't_cnt_{id}')) * float(self.t_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':
-        # Handle special cases before validation
-        if isinstance(data.get('lookup_type'), str):
-            data['lookup_type'] = ScanType[data['lookup_type'].upper()]
+        """
+        Create a ScanConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing ScanConfig parameters
+
+        Returns:
+            A new ScanConfig instance with the provided settings
+        """
 
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
-        dump = self.model_dump()
-        dump['lookup_type'] = self.lookup_type.value
-        return dump
+        """
+        Convert the ScanConfig instance to a json-serializable dictionary.
+        """
+        return self.model_dump(mode="json")
 
     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):
         a = f'subnet={self.subnet}'
         b = f'ports={self.port_list}'
-        c = f'scan_type={self.lookup_type.value}'
+        c = f'scan_type={[st.value for st in self.lookup_type]}'
         return f'ScanConfig({a}, {b}, {c})'
 
 
@@ -110,7 +260,7 @@ DEFAULT_CONFIGS: Dict[str, ScanConfig] = {
         t_cnt_isalive=64,
         task_scan_ports=True,
         task_scan_port_services=False,
-        lookup_type=ScanType.BOTH,
+        lookup_type=[ScanType.ICMP_THEN_ARP, ScanType.ARP_LOOKUP],
         arp_config=ArpConfig(
             attempts=3,
             timeout=2.5
@@ -120,6 +270,10 @@ DEFAULT_CONFIGS: Dict[str, ScanConfig] = {
             ping_count=2,
             timeout=1.5,
             retry_delay=0.5
+        ),
+        arp_cache_config=ArpCacheConfig(
+            attempts=2,
+            wait_before=0.3
         )
     ),
     'fast': ScanConfig(
@@ -130,7 +284,7 @@ DEFAULT_CONFIGS: Dict[str, ScanConfig] = {
         t_cnt_isalive=512,
         task_scan_ports=True,
         task_scan_port_services=False,
-        lookup_type=ScanType.BOTH,
+        lookup_type=[ScanType.POKE_THEN_ARP],
         arp_config=ArpConfig(
             attempts=1,
             timeout=1.0

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,46 @@ 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, JobStats
+from lanscape.libraries.net_tools import Device
+from lanscape.libraries.errors import SubnetScanTerminationFailure
+from lanscape.libraries.device_alive import is_device_alive
+
 
+class SubnetScanner():
+    """
+    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.
+    """
 
-class SubnetScanner(JobStatsMixin):
     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
+        self.job_stats = JobStats()
 
+        # Status properties
+        self.running = False
         self.uid = str(uuid.uuid4())
         self.results = ScannerResults(self)
         self.log: logging.Logger = logging.getLogger('SubnetScanner')
-        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.')
+
         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 +86,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 +123,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)
@@ -134,6 +172,7 @@ class SubnetScanner(JobStatsMixin):
             t_remain = int((100 - percent) * (t_elapsed / percent)
                            ) if percent else '∞'
             buffer = f'{self.uid} - {self.subnet_str}\n'
+            buffer += f'Config: {self.cfg}\n'
             buffer += f'Elapsed: {int(t_elapsed)} sec - Remain: {t_remain} sec\n'
             buffer += f'Scanned: {self.results.devices_scanned}/{self.results.devices_total}'
             buffer += f' - {percent}%\n'
@@ -198,12 +237,7 @@ class SubnetScanner(JobStatsMixin):
         """
         Ping the given host and return True if it's reachable, False otherwise.
         """
-        return host.is_alive(
-            host.ip,
-            scan_type=self.cfg.lookup_type,
-            ping_config=self.cfg.ping_config,
-            arp_config=self.cfg.arp_config
-        )
+        return is_device_alive(host, self.cfg)
 
     def _set_stage(self, stage):
         self.log.debug(f'[{self.uid}] Moving to Stage: {stage}')
@@ -213,41 +247,71 @@ 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] = []
 
+        # 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}')
 
+    @property
+    def devices_alive(self):
+        """number of alive devices found in the scan"""
+        return len(self.devices)
+
     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)
 
         out = vars(self).copy()
         out.pop('scan')
@@ -255,9 +319,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)
@@ -280,6 +344,7 @@ class ScannerResults:
 
         # Format and return the complete buffer with table output
         buffer = f"Scan Results - {self.scan.subnet_str} - {self.uid}\n"
+        buffer += f'Found/Scanned: {self.devices_alive}/{self.devices_scanned}\n'
         buffer += "---------------------------------------------\n\n"
         buffer += table
         return buffer
@@ -304,6 +369,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 +391,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 +402,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)