lanscape 1.3.5a2__tar.gz → 1.3.6a1__tar.gz

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

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

{lanscape-1.3.5a2 → lanscape-1.3.6a1}/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-1.3.5a2 → lanscape-1.3.6a1}/lanscape/libraries/decorators.py

@@ -25,6 +25,20 @@ class JobStats:
     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."""
         data = [
@@ -53,9 +67,7 @@ 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):
@@ -81,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

lanscape-1.3.6a1/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-1.3.5a2 → lanscape-1.3.6a1}/lanscape/libraries/net_tools.py

@@ -4,13 +4,11 @@ import logging
 import ipaddress
 import traceback
 import subprocess
-from time import sleep
 from typing import List, Dict
 import socket
 import struct
 import re
 import psutil
-from icmplib import ping
 
 from scapy.sendrecv import srp
 from scapy.layers.l2 import ARP, Ether
@@ -20,116 +18,13 @@ from lanscape.libraries.service_scan import scan_service
 from lanscape.libraries.mac_lookup import MacLookup, get_macs
 from lanscape.libraries.ip_parser import get_address_count, MAX_IPS_ALLOWED
 from lanscape.libraries.errors import DeviceError
-from lanscape.libraries.decorators import job_tracker, JobStatsMixin, timeout_enforcer
-from lanscape.libraries.scan_config import ScanType, PingConfig, ArpConfig
+from lanscape.libraries.decorators import job_tracker
 
 log = logging.getLogger('NetTools')
+mac_lookup = MacLookup()
 
 
-class IPAlive(JobStatsMixin):
-    """Class to check if a device is alive using ARP and/or ping scans."""
-    caught_errors: List[DeviceError] = []
-    _icmp_alive: bool = False
-    _arp_alive: bool = False
-
-    @job_tracker
-    def is_alive(
-        self,
-        ip: str,
-        scan_type: ScanType = ScanType.BOTH,
-        arp_config: ArpConfig = ArpConfig(),
-        ping_config: PingConfig = PingConfig()
-    ) -> bool:
-        """
-        Check if a device is alive by performing ARP and/or ping scans.
-        """
-        if scan_type == ScanType.ARP:
-            return self._arp_lookup(ip, arp_config)
-        if scan_type == ScanType.PING:
-            return self._ping_lookup(ip, ping_config)
-        return self._ping_lookup(ip, ping_config) or self._arp_lookup(ip, arp_config)
-
-    @job_tracker
-    def _arp_lookup(
-        self, ip: str,
-        cfg: ArpConfig = ArpConfig()
-    ) -> bool:
-        """Perform an ARP lookup to check if the device is alive."""
-        enforcer_timeout = cfg.timeout * 1.3
-
-        @timeout_enforcer(enforcer_timeout, raise_on_timeout=True)
-        def do_arp_lookup():
-            arp_request = ARP(pdst=ip)
-            broadcast = Ether(dst="ff:ff:ff:ff:ff:ff")
-            packet = broadcast / arp_request
-
-            answered, _ = srp(packet, timeout=cfg.timeout, verbose=False)
-            self._arp_alive = any(resp.psrc == ip for _, resp in answered)
-            return self._arp_alive
-
-        try:
-            for _ in range(cfg.attempts):
-                if do_arp_lookup():
-                    return True
-        except Exception as e:
-            self.caught_errors.append(DeviceError(e))
-        return False
-
-    @job_tracker
-    def _ping_lookup(
-        self, ip: str,
-        cfg: PingConfig = PingConfig()
-    ) -> bool:
-        """Perform a ping lookup to check if the device is alive using icmplib."""
-        enforcer_timeout = cfg.timeout * cfg.ping_count * 1.3
-
-        @timeout_enforcer(enforcer_timeout, raise_on_timeout=False)
-        def do_icmp_ping():
-            try:
-                result = ping(
-                    ip,
-                    count=cfg.ping_count,
-                    interval=cfg.retry_delay,
-                    timeout=cfg.timeout,
-                    privileged=psutil.WINDOWS  # Use privileged mode on Windows
-                )
-                return result.is_alive
-            except Exception as e:
-                self.caught_errors.append(DeviceError(e))
-                # Fallback to system ping command
-                try:
-                    if psutil.WINDOWS:
-                        cmd = [
-                            "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]
-
-                    result = subprocess.run(
-                        cmd, stdout=subprocess.PIPE,
-                        stderr=subprocess.PIPE,
-                        text=True, check=False
-                    )
-                    return result.returncode == 0
-                except subprocess.CalledProcessError as fallback_error:
-                    self.caught_errors.append(DeviceError(fallback_error))
-                    return False
-
-        try:
-            for _ in range(cfg.attempts):
-                if do_icmp_ping():
-                    self._icmp_alive = True
-                    return True
-                sleep(cfg.retry_delay)
-        except Exception as e:
-            self.caught_errors.append(DeviceError(e))
-        self._icmp_alive = False
-        return False
-
-
-class Device(IPAlive):
+class Device:
     """Represents a network device with metadata and scanning capabilities."""
 
     def __init__(self, ip: str):
@@ -144,13 +39,12 @@ class Device(IPAlive):
         self.services: Dict[str, List[int]] = {}
         self.caught_errors: List[DeviceError] = []
         self.log = logging.getLogger('Device')
-        self._mac_lookup = MacLookup()
 
     def get_metadata(self):
         """Retrieve metadata such as hostname and MAC addresses."""
         if self.alive:
             self.hostname = self._get_hostname()
-            self.macs = self._get_mac_addresses()
+            self._get_mac_addresses()
 
     def dict(self) -> dict:
         """Convert the device object to a dictionary."""
@@ -191,9 +85,12 @@ class Device(IPAlive):
     @job_tracker
     def _get_mac_addresses(self):
         """Get the possible MAC addresses of a network device given its IP address."""
-        macs = get_macs(self.ip)
-        mac_selector.import_macs(macs)
-        return macs
+        # job may already be done depending on
+        # the strat from isalive
+        if not self.macs:
+            self.macs = get_macs(self.ip)
+        mac_selector.import_macs(self.macs)
+        return self.macs
 
     @job_tracker
     def _get_hostname(self):
@@ -208,7 +105,7 @@ class Device(IPAlive):
     @job_tracker
     def _get_manufacturer(self, mac_addr=None):
         """Get the manufacturer of a network device given its MAC address."""
-        return self._mac_lookup.lookup_vendor(mac_addr) if mac_addr else None
+        return mac_lookup.lookup_vendor(mac_addr) if mac_addr else None
 
 
 class MacSelector:
@@ -562,19 +459,32 @@ def smart_select_primary_subnet(subnets: List[dict] = None) -> str:
     return selected.get("subnet", "")
 
 
+class ArpSupportChecker:
+    """
+    Singleton class to check if ARP requests are supported on the current system.
+    The check is only performed once.
+    """
+    _supported = None
+
+    @classmethod
+    def is_supported(cls):
+        """one time check if ARP requests are supported on this system"""
+        if cls._supported is not None:
+            return cls._supported
+        try:
+            arp_request = ARP(pdst='0.0.0.0')
+            broadcast = Ether(dst="ff:ff:ff:ff:ff:ff")
+            packet = broadcast / arp_request
+            srp(packet, timeout=0, verbose=False)
+            cls._supported = True
+        except (Scapy_Exception, PermissionError, RuntimeError):
+            cls._supported = False
+        return cls._supported
+
+
 def is_arp_supported():
     """
-    Check if ARP requests are supported on the current platform.
+    Check if ARP requests are supported on the current system.
+    Only runs the check once.
     """
-    try:
-        arp_request = ARP(pdst='0.0.0.0')
-        broadcast = Ether(dst="ff:ff:ff:ff:ff:ff")
-        packet = broadcast / arp_request
-
-        srp(packet, timeout=0, verbose=False)
-        return True
-    # Scapy_Exception = MacOS
-    # PermissionError = Linux
-    # RuntimeError = Windows
-    except (Scapy_Exception, PermissionError, RuntimeError):
-        return False
+    return ArpSupportChecker.is_supported()

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

@@ -4,6 +4,7 @@ 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 enum import Enum
@@ -90,17 +91,81 @@ class ArpConfig(BaseModel):
         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):
     """
     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'
+    ICMP = 'ICMP'
+    ARP_LOOKUP = 'ARP_LOOKUP'
+    POKE_THEN_ARP = 'POKE_THEN_ARP'
+    ICMP_THEN_ARP = 'ICMP_THEN_ARP'
 
 
 class ScanConfig(BaseModel):
@@ -113,18 +178,20 @@ class ScanConfig(BaseModel):
     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:
         """
@@ -143,32 +210,20 @@ class ScanConfig(BaseModel):
         """
         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()]
 
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
         """
-        Convert the ScanConfig instance to a dictionary.
-
-        Handles special cases like converting Enum values to strings.
-
-        Returns:
-            Dictionary representation of the ScanConfig
+        Convert the ScanConfig instance to a json-serializable dictionary.
         """
-        dump = self.model_dump()
-        dump['lookup_type'] = self.lookup_type.value
-        return dump
+        return self.model_dump(mode="json")
 
     def get_ports(self) -> List[int]:
         """
@@ -191,7 +246,7 @@ class ScanConfig(BaseModel):
     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})'
 
 
@@ -205,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
@@ -215,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(
@@ -225,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