lanscape 1.3.5a2__tar.gz → 1.3.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lanscape
-Version: 1.3.5a2
+Version: 1.3.6
 Summary: A python based local network scanner
 Author-email: Michael Dennis <michael@dipduo.com>
 License-Expression: MIT
@@ -25,9 +25,28 @@ Dynamic: license-file
 # LANscape
 A python based local network scanner.
 
-![screenshot](https://github.com/user-attachments/assets/ba09c656-9fd9-4d74-8426-506d9a5c316c)
+![screenshot](https://github.com/user-attachments/assets/7d77741e-3bad-4b6b-a33f-6a392adde23f)
 
-## Local Run
+
+PyPi Stats: 
+
+![Version](https://img.shields.io/pypi/v/lanscape)
+![Monthly Downloads](https://img.shields.io/pypi/dm/lanscape)
+
+Latest release: 
+
+![Stable](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=releases%2F*&label=Stable)
+![Beta](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=pre-releases%2F*b*&label=Beta)
+![Alpha](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=pre-releases%2F*a*&label=Alpha)
+
+Health: 
+
+![pytest](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/test.yml?branch=main&label=pytest) 
+![packaging](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/test-package.yml?label=packaging) 
+![pylint](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/pylint.yml?branch=main&label=pylint)
+
+
+## Installation
 ```sh
 pip install lanscape
 python -m lanscape
@@ -55,16 +74,14 @@ The program does an ARP lookup to determine the MAC address. This lookup
 can sometimes require admin-level permissions to retrieve accurate results.
 *Try elevating your shell before execution.*
 
-### Message "WARNING: No libpcap provider available ! pcap won't be used"
-This is a missing dependency related to the ARP lookup. This is handled in the code, but you would get marginally faster/better results with this installed: [npcap download](https://npcap.com/#download)
-
 ### The accuracy of the devices found is low
-I use a combination of ARP and Ping to determine if a device is online. This method drops in stability when used in many threads. 
+I use a combination of ARP, ICMP & port testing to determine if a device is online. Sometimes the scan settings can use some tuning to maximize both speed and accuracy.
+
 Recommendations:
 
-  - Drop parallelism value (advanced dropdown)
-  - Use python > 3.10 im noticing threadpool improvements after this version
-  - Create a bug - I'm curious
+  - Adjust scan configuration
+  - Configure ARP lookup [ARP lookup setup](./support/arp-issues.md)
+  - Create a bug
 
 
 ### Something else

lanscape-1.3.6/README.md

@@ -0,0 +1,66 @@
+# LANscape
+A python based local network scanner.
+
+![screenshot](https://github.com/user-attachments/assets/7d77741e-3bad-4b6b-a33f-6a392adde23f)
+
+
+PyPi Stats: 
+
+![Version](https://img.shields.io/pypi/v/lanscape)
+![Monthly Downloads](https://img.shields.io/pypi/dm/lanscape)
+
+Latest release: 
+
+![Stable](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=releases%2F*&label=Stable)
+![Beta](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=pre-releases%2F*b*&label=Beta)
+![Alpha](https://img.shields.io/github/v/tag/mdennis281/LANScape?filter=pre-releases%2F*a*&label=Alpha)
+
+Health: 
+
+![pytest](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/test.yml?branch=main&label=pytest) 
+![packaging](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/test-package.yml?label=packaging) 
+![pylint](https://img.shields.io/github/actions/workflow/status/mdennis281/LANscape/pylint.yml?branch=main&label=pylint)
+
+
+## Installation
+```sh
+pip install lanscape
+python -m lanscape
+```
+
+## Flags
+ - `--port <port number>` port of the flask app (default: automagic)
+ - `--persistent` dont shutdown server when browser tab is closed (default: false)
+ - `--reloader` essentially flask debug mode- good for local development (default: false)
+ - `--logfile <path>` save log output to the given file path
+ - `--loglevel <level>` set the logger's log level (default: INFO)
+ - `--flask-logging` turn on flask logging (default: false)
+
+Examples:
+```shell
+python -m lanscape --reloader
+python -m lanscape --port 5002
+python -m lanscape --logfile /tmp/lanscape.log --loglevel DEBUG
+```
+
+## Troubleshooting
+
+### MAC Address / Manufacturer is inaccurate/unknown
+The program does an ARP lookup to determine the MAC address. This lookup
+can sometimes require admin-level permissions to retrieve accurate results.
+*Try elevating your shell before execution.*
+
+### The accuracy of the devices found is low
+I use a combination of ARP, ICMP & port testing to determine if a device is online. Sometimes the scan settings can use some tuning to maximize both speed and accuracy.
+
+Recommendations:
+
+  - Adjust scan configuration
+  - Configure ARP lookup [ARP lookup setup](./support/arp-issues.md)
+  - Create a bug
+
+
+### Something else
+Feel free to submit a github issue detailing your experience.
+
+

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

@@ -0,0 +1,229 @@
+"""
+Handles device alive checks using various methods.
+"""
+
+import re
+import socket
+import subprocess
+import time
+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():
+            # Use a small set of common ports likely to be filtered but still trigger ARP
+            common_ports = [80, 443, 22]
+            for i in range(cfg.attempts):
+                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                sock.settimeout(cfg.timeout)
+                port = common_ports[i % len(common_ports)]
+                sock.connect_ex((device.ip, port))
+                sock.close()
+
+        do_poke()

{lanscape-1.3.5a2 → lanscape-1.3.6}/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()