easymanet 0.1.0__py3-none-any.whl

easymanet/__init__.py

@@ -0,0 +1,3 @@
+"""EasyMANET - Zero-touch OpenMANET provisioning and imaging."""
+
+__version__ = "0.1.0"

easymanet/disks/__init__.py

@@ -0,0 +1,73 @@
+"""Disk detection and listing for macOS and Linux."""
+
+import glob
+import os
+import subprocess
+
+from ..platform import is_linux, is_macos
+from ._common import (
+    DISK_PARSE_ERRORS,
+    DISK_SUSPICIOUS_SIZE_GB,
+    DISK_WARN_THRESHOLD_GB,
+    OVERLAY_WIPE_BLOCK_MIB,
+    OVERLAY_WIPE_BLOCKS,
+    SYS_MOUNT_POINTS,
+    DiskInfo,
+    debug_note,
+)
+from .core import (
+    assert_flash_allowed,
+    eject_disk,
+    find_disk,
+    get_partition2_wipe_range,
+    list_disks,
+    lookup_device,
+    unmount_disk,
+)
+from .linux import (
+    _check_linux_system_disk,
+    _findmnt_source,
+    _linux_base_block_device,
+    _linux_disk_from_lsblk,
+    _linux_lsblk_pkname,
+    _linux_partition2_wipe_range,
+    _linux_partitions_for_device,
+    _linux_resolve_findmnt_source,
+    _linux_root_block_devices,
+    _linux_should_list_default,
+    list_disks_linux,
+    lookup_device_linux,
+    unmount_disk_linux,
+)
+from .macos import (
+    _macos_partition2_wipe_range,
+    get_macos_partitions,
+    list_disks_macos,
+    lookup_device_macos,
+    unmount_disk_macos,
+)
+from .core import _is_block_device
+
+__all__ = [
+    "DISK_PARSE_ERRORS",
+    "DISK_SUSPICIOUS_SIZE_GB",
+    "DISK_WARN_THRESHOLD_GB",
+    "DiskInfo",
+    "OVERLAY_WIPE_BLOCK_MIB",
+    "OVERLAY_WIPE_BLOCKS",
+    "SYS_MOUNT_POINTS",
+    "assert_flash_allowed",
+    "debug_note",
+    "eject_disk",
+    "find_disk",
+    "get_macos_partitions",
+    "get_partition2_wipe_range",
+    "glob",
+    "is_linux",
+    "is_macos",
+    "list_disks",
+    "lookup_device",
+    "os",
+    "subprocess",
+    "unmount_disk",
+]

easymanet/disks/_common.py

@@ -0,0 +1,88 @@
+"""Shared disk types and helpers."""
+
+import plistlib
+import subprocess
+import sys
+from typing import List, Optional
+
+_SUBPROCESS_ERRORS = (
+    subprocess.CalledProcessError,
+    subprocess.TimeoutExpired,
+    FileNotFoundError,
+)
+DISK_PARSE_ERRORS = (
+    *_SUBPROCESS_ERRORS,
+    OSError,
+    ValueError,
+    UnicodeDecodeError,
+    plistlib.InvalidFileException,
+)
+
+DISK_WARN_THRESHOLD_GB = 128
+DISK_SUSPICIOUS_SIZE_GB = 256
+
+SYS_MOUNT_POINTS = frozenset({"/", "/boot", "/boot/efi", "/home", "/var", "/usr"})
+
+OVERLAY_WIPE_BLOCK_MIB = 16
+OVERLAY_WIPE_BLOCKS = 288
+
+
+def debug_note(message: str) -> None:
+    print(f"easymanet: {message}", file=sys.stderr)
+
+
+class DiskInfo:
+    def __init__(
+        self,
+        device: str,
+        size_bytes: int = 0,
+        model: str = "",
+        removable: bool = False,
+        mounted: Optional[List[str]] = None,
+        is_system: bool = False,
+        not_in_default_list: bool = False,
+    ):
+        self.device = device
+        self.size_bytes = size_bytes
+        self.model = model
+        self.removable = removable
+        self.mounted = mounted or []
+        self.is_system = is_system
+        self.not_in_default_list = not_in_default_list
+
+    @property
+    def size_gb(self) -> float:
+        return self.size_bytes / (1024 ** 3)
+
+    @property
+    def size_human(self) -> str:
+        gb = self.size_gb
+        if gb < 1:
+            mb = self.size_bytes / (1024 ** 2)
+            return f"{mb:.1f} MB"
+        return f"{gb:.1f} GB"
+
+    @property
+    def blocking_warnings(self) -> List[str]:
+        w: List[str] = []
+        if self.is_system:
+            w.append(
+                "WARNING: This appears to be a system disk — use --force to override"
+            )
+        elif not self.removable and self.size_gb > DISK_WARN_THRESHOLD_GB:
+            w.append(
+                "WARNING: Large fixed disk — use --force to proceed"
+            )
+        elif self.size_gb > DISK_SUSPICIOUS_SIZE_GB:
+            w.append(
+                "WARNING: Suspiciously large device — use --force to proceed"
+            )
+        if self.not_in_default_list:
+            w.append(
+                "WARNING: Device not in default disk list — use --force to proceed"
+            )
+        return w
+
+    @property
+    def warnings(self) -> List[str]:
+        return self.blocking_warnings

easymanet/disks/core.py

@@ -0,0 +1,139 @@
+"""Cross-platform disk listing and flash safety."""
+
+import os
+import stat
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+from ._common import (
+    OVERLAY_WIPE_BLOCK_MIB,
+    OVERLAY_WIPE_BLOCKS,
+    DiskInfo,
+)
+
+
+def _disks_module():
+    return sys.modules[__package__]
+
+
+def _is_block_device(path: str) -> bool:
+    if not os.path.exists(path):
+        return False
+    try:
+        return stat.S_ISBLK(os.stat(path).st_mode)
+    except OSError:
+        return False
+
+
+def list_disks(include_all: bool = False) -> List[DiskInfo]:
+    disks_mod = _disks_module()
+    if disks_mod.is_macos():
+        disks = disks_mod.list_disks_macos(include_all=include_all)
+    elif disks_mod.is_linux():
+        disks = disks_mod.list_disks_linux(include_all=include_all)
+    else:
+        return []
+    return sorted(disks, key=lambda d: d.size_bytes, reverse=True)
+
+
+def lookup_device(
+    device: str,
+    default_disks: Optional[List[DiskInfo]] = None,
+) -> Optional[DiskInfo]:
+    disks_mod = _disks_module()
+    if disks_mod.is_macos():
+        disk = disks_mod.lookup_device_macos(device)
+    elif disks_mod.is_linux():
+        disk = disks_mod.lookup_device_linux(device)
+    else:
+        disk = None
+
+    if disk is None:
+        return None
+
+    disks = (
+        default_disks
+        if default_disks is not None
+        else disks_mod.list_disks(include_all=False)
+    )
+    if not any(d.device == device for d in disks):
+        disk.not_in_default_list = True
+    return disk
+
+
+def find_disk(device: str) -> Optional[DiskInfo]:
+    disks = list_disks()
+    for disk in disks:
+        if disk.device == device:
+            return disk
+    return lookup_device(device, default_disks=disks)
+
+
+def assert_flash_allowed(device: str, force: bool = False) -> DiskInfo:
+    if not _disks_module()._is_block_device(device):
+        raise ValueError(
+            f"Device {device} does not exist or is not a block device."
+        )
+
+    disk = _disks_module().lookup_device(device)
+    if disk is None:
+        raise ValueError(
+            f"Could not read disk information for {device}."
+        )
+
+    blocking = disk.blocking_warnings
+    if blocking and not force:
+        lines = "\n".join(f"  {w}" for w in blocking)
+        raise ValueError(
+            f"Refusing to flash {device}:\n{lines}\n"
+            f"  Model: {disk.model}\n"
+            f"  Size: {disk.size_human}\n"
+            f"  Mounted: {', '.join(disk.mounted) if disk.mounted else 'none'}\n"
+            f"Use --force to override."
+        )
+    return disk
+
+
+def unmount_disk(device: str) -> None:
+    disks_mod = _disks_module()
+    if disks_mod.is_macos():
+        disks_mod.unmount_disk_macos(device)
+    elif disks_mod.is_linux():
+        disks_mod.unmount_disk_linux(device)
+
+
+def get_partition2_wipe_range(device: str) -> Optional[Tuple[int, int]]:
+    """Return (start_byte_offset, wipe_bytes) for partition 2 stale-overlay tail wipe."""
+    max_wipe = OVERLAY_WIPE_BLOCK_MIB * OVERLAY_WIPE_BLOCKS * 1024 * 1024
+    disks_mod = _disks_module()
+
+    if disks_mod.is_linux():
+        return disks_mod._linux_partition2_wipe_range(device, max_wipe)
+    if disks_mod.is_macos():
+        return disks_mod._macos_partition2_wipe_range(device, max_wipe)
+    return None
+
+
+def eject_disk(device: str) -> None:
+    disks_mod = _disks_module()
+    if disks_mod.is_macos():
+        result = subprocess.run(
+            ["diskutil", "eject", device],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    elif disks_mod.is_linux():
+        result = subprocess.run(
+            ["eject", device],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    else:
+        return
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        suffix = f": {detail}" if detail else ""
+        raise RuntimeError(f"Failed to eject {device}{suffix}")

easymanet/disks/linux.py

@@ -0,0 +1,306 @@
+"""Linux disk discovery and safety helpers."""
+
+import glob
+import json
+import os
+import re
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+from ._common import DISK_PARSE_ERRORS, DiskInfo, debug_note
+
+_FINDMNT_PARENT_RESOLUTION_MAX_DEPTH = 8
+_LINUX_DEFAULT_LOGICAL_SECTOR_BYTES = 512
+
+
+def _disks_module():
+    return sys.modules[__package__]
+
+
+def _parse_lsblk_size(size_str: str) -> int:
+    try:
+        return int(size_str)
+    except ValueError:
+        suffixes = {"K": 1024, "M": 1024**2, "G": 1024**3, "T": 1024**4}
+        try:
+            num = float(size_str[:-1])
+            suffix = size_str[-1].upper()
+            return int(num * suffixes.get(suffix, 1))
+        except (ValueError, IndexError):
+            return 0
+
+
+def _get_linux_mounts(dev: dict) -> List[str]:
+    mounts = []
+    children = dev.get("children", [])
+    for child in children:
+        mp = child.get("mountpoint")
+        if mp:
+            mounts.append(mp)
+    return mounts
+
+
+def _linux_disk_from_lsblk(dev: dict) -> DiskInfo:
+    dev_name = dev.get("name", "")
+    dev_path = f"/dev/{dev_name}"
+    model = (dev.get("model") or "").strip() or dev_name
+    removable = dev.get("rm", "0") == "1"
+    tran = (dev.get("tran") or "").lower()
+    if tran in ("usb", "mmc"):
+        removable = True
+    size_bytes = _parse_lsblk_size(dev.get("size", "0"))
+    mounted = _get_linux_mounts(dev)
+    is_system = _check_linux_system_disk(dev_path, mounted)
+    return DiskInfo(
+        device=dev_path,
+        size_bytes=size_bytes,
+        model=model,
+        removable=removable,
+        mounted=mounted,
+        is_system=is_system,
+    )
+
+
+def _linux_should_list_default(dev: dict) -> bool:
+    if dev.get("type") != "disk":
+        return False
+    if dev.get("rm", "0") == "1":
+        return True
+    tran = (dev.get("tran") or "").lower()
+    return tran in ("usb", "mmc")
+
+
+def _linux_lsblk_data(device: Optional[str] = None) -> Optional[dict]:
+    cmd = [
+        "lsblk",
+        "-J",
+        "-o",
+        "NAME,SIZE,TYPE,MOUNTPOINT,MODEL,RM,ROTA,TRAN",
+    ]
+    if device:
+        cmd.extend(["-n", device])
+    try:
+        output = subprocess.check_output(cmd, timeout=10).decode()
+        return json.loads(output)
+    except (
+        subprocess.CalledProcessError,
+        FileNotFoundError,
+        json.JSONDecodeError,
+        subprocess.TimeoutExpired,
+    ):
+        return None
+
+
+def list_disks_linux(include_all: bool = False) -> List[DiskInfo]:
+    data = _linux_lsblk_data()
+    if not data:
+        return []
+
+    disks: List[DiskInfo] = []
+    for dev in data.get("blockdevices", []):
+        if dev.get("type") != "disk":
+            continue
+        if not include_all and not _linux_should_list_default(dev):
+            continue
+        disks.append(_linux_disk_from_lsblk(dev))
+
+    return sorted(disks, key=lambda d: d.size_bytes, reverse=True)
+
+
+def lookup_device_linux(device: str) -> Optional[DiskInfo]:
+    data = _linux_lsblk_data(device)
+    if not data:
+        return None
+    blockdevs = data.get("blockdevices", [])
+    if not blockdevs:
+        return None
+    dev = blockdevs[0]
+    if dev.get("type") != "disk":
+        return None
+    return _linux_disk_from_lsblk(dev)
+
+
+def _findmnt_source(mount_point: str) -> Optional[str]:
+    try:
+        output = subprocess.check_output(
+            ["findmnt", "-n", "-o", "SOURCE", mount_point],
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+        ).decode()
+        return output.strip() or None
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+
+def _linux_base_block_device(source: str) -> Optional[str]:
+    if not source.startswith("/dev/"):
+        return None
+    match = re.match(r"^(?P<base>/dev/(?:mmcblk\d+|nvme\d+n\d+))p\d+$", source)
+    if match:
+        return match.group("base")
+    match = re.match(r"^(?P<base>/dev/[a-z]+)\d+$", source)
+    if match:
+        return match.group("base")
+    if re.match(r"^/dev/(?:mmcblk\d+|nvme\d+n\d+|[a-z]+)$", source):
+        return source
+    return None
+
+
+def _linux_lsblk_pkname(device: str) -> Optional[str]:
+    try:
+        output = subprocess.check_output(
+            ["lsblk", "-no", "PKNAME", device],
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+        ).decode()
+        name = output.strip()
+        if name:
+            return f"/dev/{name}"
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    return None
+
+
+def _linux_resolve_findmnt_source(source: str) -> Optional[str]:
+    disks_mod = _disks_module()
+    device_path: Optional[str] = None
+    if source.startswith("UUID="):
+        uuid = source.split("=", 1)[1]
+        by_uuid = f"/dev/disk/by-uuid/{uuid}"
+        if disks_mod.os.path.exists(by_uuid):
+            device_path = disks_mod.os.path.realpath(by_uuid)
+    elif source.startswith("PARTUUID="):
+        partuuid = source.split("=", 1)[1]
+        by_partuuid = f"/dev/disk/by-partuuid/{partuuid}"
+        if disks_mod.os.path.exists(by_partuuid):
+            device_path = disks_mod.os.path.realpath(by_partuuid)
+    elif source.startswith("/dev/"):
+        device_path = disks_mod.os.path.realpath(source)
+    else:
+        return None
+
+    if not device_path:
+        return None
+
+    current = device_path
+    for _ in range(_FINDMNT_PARENT_RESOLUTION_MAX_DEPTH):
+        base = disks_mod._linux_base_block_device(current)
+        if base:
+            return base
+        parent = disks_mod._linux_lsblk_pkname(current)
+        if not parent or parent == current:
+            break
+        current = parent
+    return None
+
+
+def _linux_partitions_for_device(device: str) -> List[str]:
+    partitions = set()
+    for pattern in (f"{device}[0-9]*", f"{device}p[0-9]*"):
+        partitions.update(_disks_module().glob.glob(pattern))
+    partitions.discard(device)
+    return sorted(partitions)
+
+
+def _linux_root_block_devices() -> set:
+    disks_mod = _disks_module()
+    related: set = set()
+    for mount_point in sorted(disks_mod.SYS_MOUNT_POINTS):
+        source = disks_mod._findmnt_source(mount_point)
+        if not source:
+            continue
+        base = disks_mod._linux_resolve_findmnt_source(source)
+        if not base:
+            continue
+        related.add(base)
+        related.update(disks_mod._linux_partitions_for_device(base))
+        if source.startswith("/dev/"):
+            resolved = disks_mod.os.path.realpath(source)
+            if resolved.startswith("/dev/"):
+                related.add(resolved)
+    return related
+
+
+def _check_linux_system_disk(dev_path: str, mounts: List[str]) -> bool:
+    disks_mod = _disks_module()
+    if any(mp in disks_mod.SYS_MOUNT_POINTS for mp in mounts):
+        return True
+
+    root_related = disks_mod._linux_root_block_devices()
+    if not root_related:
+        debug_note(
+            "could not resolve Linux root block devices; treating candidate as a system disk"
+        )
+        return True
+
+    if dev_path in root_related:
+        return True
+    if set(disks_mod._linux_partitions_for_device(dev_path)) & root_related:
+        return True
+    for entry in root_related:
+        if disks_mod._linux_base_block_device(entry) == dev_path:
+            return True
+    return False
+
+
+def _linux_partition2_wipe_range(device: str, max_wipe: int) -> Optional[Tuple[int, int]]:
+    cmd = ["lsblk", "-J", "-b", "-o", "NAME,START,SIZE,TYPE,LOG-SEC", "-n", device]
+    try:
+        output = subprocess.check_output(cmd, timeout=10).decode()
+        data = json.loads(output)
+    except (
+        subprocess.CalledProcessError,
+        FileNotFoundError,
+        json.JSONDecodeError,
+        subprocess.TimeoutExpired,
+    ):
+        return None
+
+    blockdevs = data.get("blockdevices", [])
+    if not blockdevs:
+        return None
+    children = blockdevs[0].get("children", [])
+    parts = [c for c in children if c.get("type") == "part"]
+    if len(parts) < 2:
+        return None
+    part2 = sorted(parts, key=lambda p: int(p.get("start", 0) or 0))[1]
+    start = int(part2.get("start", 0) or 0)
+    size = int(part2.get("size", 0) or 0)
+    if start <= 0 or size <= 0:
+        return None
+    sector_bytes = _linux_logical_sector_bytes(part2, blockdevs[0])
+    start_bytes = start * sector_bytes
+    wipe_bytes = min(size, max_wipe)
+    tail_start = start_bytes + size - wipe_bytes
+    return (tail_start, wipe_bytes)
+
+
+def _linux_logical_sector_bytes(*devices: dict) -> int:
+    for dev in devices:
+        for key in ("log-sec", "log_sec", "LOG-SEC"):
+            try:
+                value = int(dev.get(key, 0) or 0)
+            except (TypeError, ValueError):
+                continue
+            if value > 0:
+                return value
+    return _LINUX_DEFAULT_LOGICAL_SECTOR_BYTES
+
+
+def unmount_disk_linux(device: str) -> None:
+    targets = _linux_partitions_for_device(device) or [device]
+    for target in targets:
+        result = subprocess.run(
+            ["umount", target],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0:
+            continue
+        detail = (result.stderr or result.stdout or "").strip()
+        if "not mounted" in detail.lower():
+            continue
+        suffix = f": {detail}" if detail else ""
+        raise RuntimeError(f"Failed to unmount {target}{suffix}")