lanscape 1.3.2a7__tar.gz → 1.3.2a9__tar.gz

{lanscape-1.3.2a7/lanscape.egg-info → lanscape-1.3.2a9}/PKG-INFO

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

lanscape-1.3.2a9/lanscape/libraries/app_scope.py

@@ -0,0 +1,75 @@
+
+"""
+Resource and environment management utilities for Lanscape.
+"""
+
+from pathlib import Path
+import json
+import sys
+import re
+
+
+class ResourceManager:
+    """
+    A class to manage assets in the resources folder.
+    Works locally and if installed based on relative path from this file.
+    """
+
+    def __init__(self, asset_folder: str):
+        """Initialize the resource manager with a specific asset folder."""
+        self.asset_dir = self._get_resource_path() / asset_folder
+
+    def list(self):
+        """List all asset names in the asset directory."""
+        return [p.name for p in self.asset_dir.iterdir()]
+
+    def get(self, asset_name: str):
+        """Get the content of an asset as a string."""
+        with open(self.asset_dir / asset_name, 'r', encoding='utf-8') as f:
+            return f.read()
+
+    def get_json(self, asset_name: str):
+        """Get the content of an asset as a JSON object."""
+        return json.loads(self.get(asset_name))
+
+    def get_jsonc(self, asset_name: str):
+        """Get JSON content with comments removed."""
+        content = self.get(asset_name)
+        cleaned_content = re.sub(r'//.*', '', content)
+        return json.loads(cleaned_content)
+
+    def update(self, asset_name: str, content: str):
+        """Update the content of an existing asset."""
+        with open(self.asset_dir / asset_name, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+    def create(self, asset_name: str, content: str):
+        """Create a new asset with the given content."""
+        if (self.asset_dir / asset_name).exists():
+            raise FileExistsError(f"File {asset_name} already exists")
+        with open(self.asset_dir / asset_name, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+    def delete(self, asset_name: str):
+        """Delete an asset from the asset directory."""
+        (self.asset_dir / asset_name).unlink()
+
+    def _get_resource_path(self) -> Path:
+        """Get the path to the resources directory."""
+        base_dir = Path(__file__).parent.parent
+        resource_dir = base_dir / "resources"
+        return resource_dir
+
+
+def is_local_run() -> bool:
+    """
+    Determine if the code is running locally or as an installed PyPI package.
+    Returns True if running locally, False if installed as a package.
+    """
+    module_path = Path(__file__).parent
+
+    package_folders = ["site-packages", "dist-packages"]
+    parts = [part in module_path.parts for part in package_folders]
+    if any(parts):
+        return False
+    return True  # Installed package

lanscape-1.3.2a9/lanscape/libraries/decorators.py

@@ -0,0 +1,153 @@
+
+"""
+Decorators and job tracking utilities for Lanscape.
+"""
+
+from time import time
+from dataclasses import dataclass, field
+from typing import DefaultDict
+from collections import defaultdict
+import inspect
+import functools
+import concurrent.futures
+from tabulate import tabulate
+
+
+@dataclass
+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))
+
+    def __str__(self):
+        """Return a formatted string representation of the job statistics."""
+        data = [
+            [
+                name,
+                self.running.get(name, 0),
+                self.finished.get(name, 0),
+                self.timing.get(name, 0.0)
+            ]
+            for name in set(self.running) | set(self.finished)
+        ]
+        headers = ["Function", "Running", "Finished", "Avg Time (s)"]
+        return tabulate(
+            data,
+            headers=headers,
+            tablefmt="grid"
+        )
+
+
+class JobStatsMixin:  # pylint: disable=too-few-public-methods
+    """
+    Singleton mixin that provides shared job_stats property across all instances.
+    """
+    _job_stats = None
+
+    @property
+    def job_stats(self):
+        """Return the shared JobStats instance."""
+        if JobStatsMixin._job_stats is None:
+            JobStatsMixin._job_stats = JobStats()
+        return JobStatsMixin._job_stats
+
+
+def job_tracker(func):
+    """
+    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:
+        """
+        Return the function name with the class name prepended if available.
+        """
+        qual_parts = func.__qualname__.split(".")
+        cls_name = qual_parts[-2] if len(qual_parts) > 1 else None
+        cls_obj = None  # resolved lazily
+        if cls_obj is None and cls_name:
+            mod = inspect.getmodule(func)
+            cls_obj = getattr(mod, cls_name, None)
+        if cls_obj and first_arg is not None:
+            if (first_arg is cls_obj or isinstance(first_arg, cls_obj)):
+                return f"{cls_name}.{func.__name__}"
+        return func.__name__
+
+    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
+        fxn = get_fxn_src_name(
+            func,
+            class_instance
+        )
+
+        # Increment running counter and track execution time
+        job_stats.running[fxn] += 1
+        start = time()
+
+        result = func(*args, **kwargs)  # Execute the wrapped function
+
+        # Update statistics after function execution
+        elapsed = time() - start
+        job_stats.running[fxn] -= 1
+        job_stats.finished[fxn] += 1
+
+        # Calculate the new average timing for the function
+        job_stats.timing[fxn] = round(
+            ((job_stats.finished[fxn] - 1) * job_stats.timing[fxn] + elapsed)
+            / job_stats.finished[fxn],
+            4
+        )
+
+        # Clean up if no more running instances of this function
+        if job_stats.running[fxn] == 0:
+            job_stats.running.pop(fxn)
+
+        return result
+
+    return wrapper
+
+
+def terminator(func):
+    """
+    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."""
+        scan = args[0]  # aka self
+        if not scan.running:
+            return None
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def timeout_enforcer(timeout: int, raise_on_timeout: bool = True):
+    """
+    Decorator to enforce a timeout on a function.
+
+    Args:
+        timeout (int): Timeout length in seconds.
+        raise_on_timeout (bool): Whether to raise an exception if the timeout is exceeded.
+    """
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            """Wrap the function to enforce a timeout on its execution."""
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(func, *args, **kwargs)
+                try:
+                    return future.result(
+                        timeout=timeout
+                    )
+                except concurrent.futures.TimeoutError as exc:
+                    if raise_on_timeout:
+                        raise TimeoutError(
+                            f"Function '{func.__name__}' exceeded timeout of "
+                            f"{timeout} seconds."
+                        ) from exc
+                    return None  # Return None if not raising an exception
+        return wrapper
+    return decorator

lanscape-1.3.2a9/lanscape/libraries/errors.py

@@ -0,0 +1,32 @@
+
+
+class SubnetTooLargeError(Exception):
+    """Custom exception raised when the subnet size exceeds the allowed limit."""
+
+    def __init__(self, subnet):
+        self.subnet = subnet
+        super().__init__(f"Subnet {subnet} exceeds the limit of IP addresses.")
+
+
+class SubnetScanTerminationFailure(Exception):
+    def __init__(self, running_threads):
+        super().__init__(
+            f'Unable to terminate active threads: {running_threads}')
+
+
+class DeviceError(Exception):
+    def __init__(self, e: Exception):
+        self.base: Exception = e
+        self.method = self._attempt_extract_method()
+
+    def _attempt_extract_method(self):
+        try:
+            tb = self.base.__traceback__
+            frame = tb.tb_frame
+            return frame.f_code.co_name
+        except Exception as e:
+            print(e)
+            return 'unknown'
+
+    def __str__(self):
+        return f'Error(source={self.method}, msg={self.base})'

lanscape-1.3.2a9/lanscape/libraries/ip_parser.py

@@ -0,0 +1,69 @@
+import ipaddress
+from .errors import SubnetTooLargeError
+import re
+
+MAX_IPS_ALLOWED = 100000
+
+
+def parse_ip_input(ip_input):
+    # Split input on commas for multiple entries
+    entries = [entry.strip() for entry in ip_input.split(',')]
+    ip_ranges = []
+
+    for entry in entries:
+        # Handle CIDR notation or IP/32
+        if '/' in entry:
+            net = ipaddress.IPv4Network(entry, strict=False)
+            if net.num_addresses > MAX_IPS_ALLOWED:
+                raise SubnetTooLargeError(ip_input)
+            for ip in net.hosts():
+                ip_ranges.append(ip)
+
+        # Handle IP range (e.g., 10.0.0.15-10.0.0.25)
+        elif '-' in entry:
+            ip_ranges += parse_ip_range(entry)
+
+        # Handle shorthand IP range (e.g., 10.0.9.1-253)
+        elif re.search(r'\d+\-\d+', entry):
+            ip_ranges += parse_shorthand_ip_range(entry)
+
+        # If no CIDR or range, assume a single IP
+        else:
+            ip_ranges.append(ipaddress.IPv4Address(entry))
+        if len(ip_ranges) > MAX_IPS_ALLOWED:
+            raise SubnetTooLargeError(ip_input)
+    return ip_ranges
+
+
+def get_address_count(subnet: str):
+    try:
+        net = ipaddress.IPv4Network(subnet, strict=False)
+        return net.num_addresses
+    except BaseException:
+        return 0
+
+
+def parse_ip_range(entry):
+    start_ip, end_ip = entry.split('-')
+    start_ip = ipaddress.IPv4Address(start_ip.strip())
+
+    # Handle case where the second part is a partial IP (e.g., '253')
+    if '.' not in end_ip:
+        end_ip = start_ip.exploded.rsplit('.', 1)[0] + '.' + end_ip.strip()
+
+    end_ip = ipaddress.IPv4Address(end_ip.strip())
+    return list(ip_range_to_list(start_ip, end_ip))
+
+
+def parse_shorthand_ip_range(entry):
+    start_ip, end_part = entry.split('-')
+    start_ip = ipaddress.IPv4Address(start_ip.strip())
+    end_ip = start_ip.exploded.rsplit('.', 1)[0] + '.' + end_part.strip()
+
+    return list(ip_range_to_list(start_ip, ipaddress.IPv4Address(end_ip)))
+
+
+def ip_range_to_list(start_ip, end_ip):
+    # Yield the range of IPs
+    for ip_int in range(int(start_ip), int(end_ip) + 1):
+        yield ipaddress.IPv4Address(ip_int)

lanscape-1.3.2a9/lanscape/libraries/logger.py

@@ -0,0 +1,45 @@
+import logging
+from logging.handlers import RotatingFileHandler
+import click
+
+
+def configure_logging(loglevel: str, logfile: bool, flask_logging: bool = False) -> None:
+    numeric_level = getattr(logging, loglevel.upper(), None)
+    if not isinstance(numeric_level, int):
+        raise ValueError(f'Invalid log level: {loglevel}')
+
+    logging.basicConfig(level=numeric_level,
+                        format='[%(name)s] %(levelname)s - %(message)s')
+
+    # flask spams too much on info
+    if not flask_logging:
+        disable_flask_logging()
+
+    if logfile:
+        handler = RotatingFileHandler(
+            'lanscape.log', maxBytes=100000, backupCount=3)
+        handler.setLevel(numeric_level)
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+        handler.setFormatter(formatter)
+        logging.getLogger().addHandler(handler)
+    else:
+        # For console, it defaults to basicConfig
+        pass
+
+
+def disable_flask_logging() -> None:
+
+    def override_click_logging():
+        def secho(text, file=None, nl=None, err=None, color=None, **styles):
+            pass
+
+        def echo(text, file=None, nl=None, err=None, color=None, **styles):
+            pass
+
+        click.echo = echo
+        click.secho = secho
+    werkzeug_log = logging.getLogger('werkzeug')
+    werkzeug_log.setLevel(logging.ERROR)
+
+    override_click_logging()

lanscape-1.3.2a9/lanscape/libraries/mac_lookup.py

@@ -0,0 +1,102 @@
+import re
+import logging
+import platform
+import subprocess
+from typing import List, Optional
+from scapy.sendrecv import srp
+from scapy.layers.l2 import ARP, Ether
+from .app_scope import ResourceManager
+from .decorators import job_tracker, JobStatsMixin
+from .errors import DeviceError
+
+
+log = logging.getLogger('MacLookup')
+
+
+class MacLookup:
+    """High-level MAC address lookup service."""
+
+    def __init__(self):
+        self._db = ResourceManager('mac_addresses').get_json('mac_db.json')
+        self._resolver = MacResolver()
+
+    def lookup_vendor(self, mac: str) -> Optional[str]:
+        """
+        Lookup a MAC address in the database and return the vendor name.
+        """
+        if mac:
+            for m in self._db:
+                if mac.upper().startswith(str(m).upper()):
+                    return self._db[m]
+        return None
+
+    def resolve_mac_addresses(self, ip: str) -> List[str]:
+        """
+        Get MAC addresses for an IP address using available methods.
+        """
+        return self._resolver.get_macs(ip)
+
+
+class MacResolver(JobStatsMixin):
+    """Handles MAC address resolution using various methods."""
+
+    def __init__(self):
+        super().__init__()
+        self.caught_errors: List[DeviceError] = []
+
+    def get_macs(self, ip: str) -> List[str]:
+        """Try to get the MAC address using Scapy, fallback to ARP if it fails."""
+        if mac := self._get_mac_by_scapy(ip):
+            log.debug(f"Used Scapy to resolve ip {ip} to mac {mac}")
+            return mac
+        arp = self._get_mac_by_arp(ip)
+        log.debug(f"Used ARP to resolve ip {ip} to mac {arp}")
+        return arp
+
+    @job_tracker
+    def _get_mac_by_arp(self, ip: str) -> List[str]:
+        """Retrieve the last MAC address instance using the ARP command."""
+        try:
+            # Use the appropriate ARP command based on the platform
+            cmd = f"arp -a {ip}" if platform.system() == "Windows" else f"arp {ip}"
+
+            # Execute the ARP command and decode the output
+            output = subprocess.check_output(
+                cmd, shell=True
+            ).decode().replace('-', ':')
+
+            macs = re.findall(r'..:..:..:..:..:..', output)
+            # found that typically last mac is the correct one
+            return macs
+        except Exception as e:
+            self.caught_errors.append(DeviceError(e))
+            return []
+
+    @job_tracker
+    def _get_mac_by_scapy(self, ip: str) -> List[str]:
+        """Retrieve the MAC address using the Scapy library."""
+        try:
+            # Construct and send an ARP request
+            arp_request = ARP(pdst=ip)
+            broadcast = Ether(dst="ff:ff:ff:ff:ff:ff")
+            packet = broadcast / arp_request
+
+            # Send the packet and wait for a response
+            result = srp(packet, timeout=1, verbose=0)[0]
+
+            # Extract the MAC addresses from the response
+            return [res[1].hwsrc for res in result]
+        except Exception as e:
+            self.caught_errors.append(DeviceError(e))
+            return []
+
+
+# Backward compatibility functions
+def lookup_mac(mac: str) -> Optional[str]:
+    """Backward compatibility function for MAC vendor lookup."""
+    return MacLookup().lookup_vendor(mac)
+
+
+def get_macs(ip: str) -> List[str]:
+    """Backward compatibility function for MAC resolution."""
+    return MacResolver().get_macs(ip)