runspec-linux-core 0.7.0__tar.gz → 0.9.0__tar.gz

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/CHANGELOG.md

@@ -1,5 +1,63 @@
 # runspec-linux-core Changelog
 
+## [0.9.0] — 2026-09-26
+
+### Added
+
+- **`open_ports` flags owners it couldn't see.** `ss -p` only reports other
+  users' processes to root, so an unprivileged probe returned most listeners
+  with an empty `processes` list, which is easy to misread as "nothing owns this
+  port". When the probe didn't run as root and any owner is missing, the
+  result now carries a `hint` ("N of M listeners have no owning process …
+  Re-run with --sudo"). No hint as root, via `run_as="root"`, or when every
+  owner is known.
+- **Docker socket permission errors name the fix.** `list_containers`,
+  `container_logs` and `restart_container` turn an unescalated "permission
+  denied … docker.sock" into a `CommandError` that says to re-run with
+  `--sudo`, use `--run-as` with a docker-group user, or add the user to the
+  docker group. `container_logs` now raises on that error instead of returning
+  the daemon's refusal as log lines. Escalated failures keep the existing
+  passwordless-sudo message.
+
+## [0.8.0] — 2026-09-26
+
+### Added
+
+- **`block_devices(include_loop=False)`** — the disk inventory behind the new
+  `block-devices` runnable. Runs `lsblk --json` and returns a tree: each disk
+  with its partitions, LVM volumes and crypt/RAID layers under `children`, with
+  size, `rotational` (the kernel's SSD-vs-spinning flag), transport, model,
+  serial, filesystem, label, UUID and mount points. Normalises both the typed JSON
+  of util-linux >= 2.33 and the all-strings output of older versions, and falls
+  back from the `MOUNTPOINTS` column (>= 2.37) to `MOUNTPOINT`. Loop devices are
+  hidden unless `include_loop`.
+- **`network_interfaces(physical_only=False)`** — the NIC inventory behind the new
+  `network-interfaces` runnable, from `ip -json address` plus `/sys/class/net`:
+  state, MAC, MTU, bridge/bond `master`, and IPv4/IPv6 addresses (`dynamic` for
+  DHCP/SLAAC), plus link speed and driver for physical cards. `physical` marks an
+  interface backed by hardware; `physical_only` drops loopback, bridges, bonds,
+  VLANs, veth pairs and tunnels, which clutter a container or Kubernetes host.
+- **`find_large_files_report(search_path, min_mb, limit, *, cross_mounts=False)`**
+  — `find_large_files` as a report: `{path, min_mb, files, match_count,
+  skipped_mounts?}`, where `match_count` counts matches before `limit`.
+
+### Changed
+
+- **`find_large_files` stays on one filesystem.** It recursed across every mount
+  below `search_path`, so a scan of `/` walked `/proc` and ranked `/proc/kcore`
+  (a ~128 TiB virtual file) as the largest file on the host. It now behaves like
+  `find -xdev`. `cross_mounts=True` opts back into other mounted filesystems (a
+  separate disk, a network share), but kernel virtual filesystems (`proc`,
+  `sysfs`, `devtmpfs`, `cgroup2` …) are never scanned. They are recognised from
+  `/proc/self/mountinfo`, then `/proc/mounts`, then the `/proc` / `/sys` / `/dev`
+  paths. The guard is `runspec_linux_core._mounts`, a byte-for-byte twin of
+  `runspec_fs_core._mounts` (each core stays dependency-free) kept identical by a
+  parity test.
+- **A bad `search_path` is an error.** A missing path raises `FileNotFoundError`
+  and a file raises `NotADirectoryError`; both used to return an empty list,
+  indistinguishable from "no large files". A path on a virtual filesystem raises
+  `ValueError`.
+
 ## [0.7.0] — 2026-09-25
 
 ### Added

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runspec-linux-core
-Version: 0.7.0
+Version: 0.9.0
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.7.0"
+version = "0.9.0"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/runspec_linux_core/__init__.py

@@ -31,7 +31,7 @@ from runspec_linux_core.cron import (
     validate_schedule,
 )
 from runspec_linux_core.errors import CommandError, LinuxCoreError, ToolNotFoundError
-from runspec_linux_core.files import backup_files, find_large_files
+from runspec_linux_core.files import backup_files, find_large_files, find_large_files_report
 from runspec_linux_core.investigate import (
     failed_units,
     open_ports,
@@ -43,6 +43,7 @@ from runspec_linux_core.nc import nc_send
 from runspec_linux_core.network import (
     check_port,
     dns_config,
+    network_interfaces,
     ping_host,
     route_table,
     show_connections,
@@ -62,7 +63,7 @@ from runspec_linux_core.power import reboot_host
 from runspec_linux_core.security import last_logins, who
 from runspec_linux_core.services import check_service, list_services, restart_service
 from runspec_linux_core.sudoers import enable_passwordless_sudo
-from runspec_linux_core.system import check_memory, disk_usage, list_processes, system_info
+from runspec_linux_core.system import block_devices, check_memory, disk_usage, list_processes, system_info
 from runspec_linux_core.venvs import configure_pip, create_venv, install_into_venv, share_venv_logs
 
 __all__ = [
@@ -80,6 +81,7 @@ __all__ = [
     # system
     "system_info",
     "disk_usage",
+    "block_devices",
     "check_memory",
     "list_processes",
     # services
@@ -98,6 +100,7 @@ __all__ = [
     "route_table",
     "socket_stats",
     "dns_config",
+    "network_interfaces",
     # perf tuning & analysis
     "get_sysctl",
     "set_sysctl",
@@ -110,6 +113,7 @@ __all__ = [
     "failed_units",
     # files
     "find_large_files",
+    "find_large_files_report",
     "backup_files",
     # security
     "last_logins",

runspec_linux_core-0.9.0/runspec_linux_core/_mounts.py

@@ -0,0 +1,172 @@
+"""Mount-boundary guard for recursive disk scans.
+
+Keeps a scan that walks a directory tree from wandering into other filesystems.
+By default it stays on the filesystem it started on (the ``du -x`` /
+``find -xdev`` rule). Kernel virtual filesystems (``/proc``, ``/sys``, ``/dev``
+…) are never entered, even when crossing mounts is allowed: they hold no data on
+disk, and ``/proc/kcore`` alone reports a size of ~128 TiB.
+
+Deliberately duplicated, byte for byte, in ``runspec-linux-core`` and
+``runspec-fs-core`` (each core stays dependency-free); a parity test in each
+package keeps the two copies identical.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+#: Kernel pseudo filesystems with no disk behind them — never scanned.
+VIRTUAL_FSTYPES = frozenset(
+    {
+        "autofs",
+        "binfmt_misc",
+        "bpf",
+        "cgroup",
+        "cgroup2",
+        "configfs",
+        "debugfs",
+        "devpts",
+        "devtmpfs",
+        "efivarfs",
+        "fusectl",
+        "hugetlbfs",
+        "mqueue",
+        "nsfs",
+        "proc",
+        "pstore",
+        "rpc_pipefs",
+        "securityfs",
+        "selinuxfs",
+        "sysfs",
+        "tracefs",
+    }
+)
+
+#: The standard virtual trees and their usual type, used when the mount table
+#: can't be read or doesn't list a path (POSIX only).
+FALLBACK_VIRTUAL_PREFIXES = {"/proc": "proc", "/sys": "sysfs", "/dev": "devtmpfs"}
+
+_OCTAL_ESCAPE = re.compile(r"\\([0-7]{3})")
+
+
+def _unescape(field: str) -> str:
+    """Decode the octal escapes (``\\040`` for a space …) used in mount tables."""
+    return _OCTAL_ESCAPE.sub(lambda m: chr(int(m.group(1), 8)), field)
+
+
+def parse_mountinfo(text: str) -> dict[str, str]:
+    """Map mount point → filesystem type from ``/proc/self/mountinfo`` text.
+
+    Each line is ``id parent major:minor root mount-point options [optional …]
+    - fstype source super-options``. When a mount point is listed more than once
+    the last line wins — it is the mount on top, the one a path resolves to.
+    """
+    types: dict[str, str] = {}
+    for line in text.splitlines():
+        left, sep, right = line.partition(" - ")
+        fields, tail = left.split(), right.split()
+        if sep and len(fields) >= 5 and tail:
+            types[_unescape(fields[4])] = tail[0]
+    return types
+
+
+def parse_proc_mounts(text: str) -> dict[str, str]:
+    """Map mount point → filesystem type from ``/proc/mounts`` text
+    (``source mount-point fstype options dump pass``)."""
+    types: dict[str, str] = {}
+    for line in text.splitlines():
+        fields = line.split()
+        if len(fields) >= 3:
+            types[_unescape(fields[1])] = fields[2]
+    return types
+
+
+def read_mount_types(
+    mountinfo: str = "/proc/self/mountinfo",
+    mounts: str = "/proc/mounts",
+) -> dict[str, str] | None:
+    """The live mount table as ``{mount point: fstype}``, or ``None`` when it
+    can't be read (not Linux, or a restricted ``/proc``)."""
+    for path, parse in ((mountinfo, parse_mountinfo), (mounts, parse_proc_mounts)):
+        try:
+            with open(path, encoding="utf-8", errors="surrogateescape") as f:
+                types = parse(f.read())
+        except OSError:
+            continue
+        if types:
+            return types
+    return None
+
+
+class MountGuard:
+    """Decides which directories a recursive scan may enter.
+
+    With ``cross_mounts=False`` (the default) the scan stays on the filesystem it
+    started on. With ``True`` it may enter other mounted filesystems (a separate
+    ``/home`` disk, a network share), but never a virtual one. Each directory the
+    scan refuses to enter is counted in :attr:`skipped_mounts`.
+
+    Raises :class:`ValueError` when ``root`` itself is on a virtual filesystem —
+    there is nothing on disk there to measure. On Windows only the device
+    comparison applies; there is no mount table to consult.
+    """
+
+    def __init__(
+        self,
+        root: str | os.PathLike[str],
+        *,
+        cross_mounts: bool = False,
+        mount_types: dict[str, str] | None = None,
+    ) -> None:
+        self.cross_mounts = cross_mounts
+        self.skipped_mounts = 0
+        self._posix = os.name == "posix"
+        if mount_types is not None:
+            self._types: dict[str, str] | None = mount_types
+        else:
+            self._types = read_mount_types() if self._posix else None
+        fstype = self._virtual_type(os.fspath(root), containing=True)
+        if fstype:
+            raise ValueError(f"{os.fspath(root)} is on a virtual filesystem ({fstype}); it holds no files on disk to measure")
+
+    def enter(self, path: str, dev: int, parent_dev: int) -> bool:
+        """Whether the scan may descend into directory ``path`` (on device
+        ``dev``) from its parent directory (on device ``parent_dev``). A refusal
+        is counted in :attr:`skipped_mounts`."""
+        if dev == parent_dev:
+            return True
+        if self.cross_mounts and self._virtual_type(path, containing=False) is None:
+            return True
+        self.skipped_mounts += 1
+        return False
+
+    def _virtual_type(self, path: str, *, containing: bool) -> str | None:
+        """The virtual filesystem type at ``path`` — the mount point itself, or
+        with ``containing`` the mount the path lies in — or ``None`` if the
+        filesystem there is a real one."""
+        if not self._posix:
+            return None
+        real = os.path.realpath(path)
+        fstype = self._mount_type(real, containing=containing)
+        if fstype is not None:
+            return fstype if fstype in VIRTUAL_FSTYPES else None
+        for prefix, prefix_type in FALLBACK_VIRTUAL_PREFIXES.items():
+            if real == prefix or real.startswith(prefix + "/"):
+                return prefix_type
+        return None
+
+    def _mount_type(self, real: str, *, containing: bool) -> str | None:
+        """The table's fstype for mount point ``real``, or with ``containing``
+        for the longest mount point that ``real`` lies under."""
+        if not self._types:
+            return None
+        if not containing:
+            return self._types.get(real)
+        best: str | None = None
+        best_len = -1
+        for mount_point, fstype in self._types.items():
+            under = mount_point if mount_point.endswith("/") else mount_point + "/"
+            if (real == mount_point or real.startswith(under)) and len(mount_point) > best_len:
+                best, best_len = fstype, len(mount_point)
+        return best

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/runspec_linux_core/containers.py

@@ -12,13 +12,28 @@ import shutil
 import subprocess
 
 from runspec_linux_core.become import build_become, check_become_error
-from runspec_linux_core.errors import ToolNotFoundError
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
 
 
 def _docker_available() -> bool:
     return shutil.which("docker") is not None
 
 
+def _check_docker_error(what: str, stderr: str, run_as: str | None) -> None:
+    """Raise :class:`CommandError` for a failed ``docker`` command.
+
+    An unescalated call refused by the daemon socket (root-owned, or limited to
+    the ``docker`` group) gets an actionable message naming the fix, so the
+    caller retries escalated instead of reporting "no containers". Anything else
+    goes through :func:`check_become_error` (passwordless-sudo hint when escalated).
+    """
+    err = stderr.strip()
+    low = err.lower()
+    if not run_as and "permission denied" in low and "docker" in low:
+        raise CommandError(f"{what}: {err} — this user can't reach the Docker socket. Re-run with --sudo (or --run-as a user in the docker group), or add this user to the docker group.")
+    check_become_error(what, stderr, run_as)
+
+
 def list_containers(include_all: bool = False, *, run_as: str | None = None, become_method: str = "sudo") -> list[dict]:
     """Return Docker containers (running, or all if ``include_all``).
 
@@ -40,7 +55,7 @@ def list_containers(include_all: bool = False, *, run_as: str | None = None, bec
 
     result = subprocess.run(build_become(cmd, run_as, become_method), capture_output=True, text=True)
     if result.returncode != 0:
-        check_become_error("list containers", result.stderr, run_as)
+        _check_docker_error("list containers", result.stderr, run_as)
 
     rows = []
     for line in result.stdout.strip().splitlines():
@@ -72,8 +87,9 @@ def container_logs(container: str, lines: int = 50, *, run_as: str | None = None
 
     argv = build_become(["docker", "logs", "--tail", str(lines), container], run_as, become_method)
     result = subprocess.run(argv, capture_output=True, text=True)
-    if run_as and result.returncode != 0:
-        check_become_error("container logs", result.stderr, run_as)
+    if result.returncode != 0 and (run_as or "permission denied" in result.stderr.lower()):
+        # Escalation failures, and a refused Docker socket, are errors — not log lines.
+        _check_docker_error("container logs", result.stderr, run_as)
     # docker logs writes to stderr by default
     output = result.stderr if result.stderr else result.stdout
     output_lines = output.strip().splitlines()
@@ -95,7 +111,7 @@ def restart_container(container: str, *, run_as: str | None = None, become_metho
 
     result = subprocess.run(build_become(["docker", "restart", container], run_as, become_method), capture_output=True, text=True)
     if result.returncode != 0:
-        check_become_error("restart container", result.stderr, run_as)
+        _check_docker_error("restart container", result.stderr, run_as)
     out = {"container": container, "restarted": True}
     if run_as:
         out["run_as"] = run_as

runspec_linux_core-0.9.0/runspec_linux_core/files.py

@@ -0,0 +1,107 @@
+"""File helpers: find large files, create a timestamped tar.gz backup."""
+
+import os
+import stat
+import tarfile
+from datetime import datetime
+from pathlib import Path
+
+from runspec_linux_core._mounts import MountGuard
+
+
+def find_large_files_report(search_path: str, min_mb: float = 100.0, limit: int = 50, *, cross_mounts: bool = False) -> dict:
+    """Find files under ``search_path`` at least ``min_mb`` MB, biggest first.
+
+    The scan stays on the filesystem ``search_path`` is on, like
+    ``find -xdev``, unless ``cross_mounts`` is set. Kernel virtual filesystems
+    (``/proc``, ``/sys``, ``/dev`` …) are never scanned either way, so a scan of
+    ``/`` can't report ``/proc/kcore`` as a ~128 TiB file. Directories not
+    entered for either reason are counted in ``skipped_mounts`` (present only
+    when non-zero).
+
+    Returns ``{path, min_mb, files: [{path, size_mb, modified}], match_count,
+    skipped_mounts?}``, where ``match_count`` is the number of matching files
+    before ``limit`` is applied. Raises ``FileNotFoundError`` /
+    ``NotADirectoryError`` for a bad ``search_path`` and ``ValueError`` when it
+    is on a virtual filesystem.
+    """
+    if not os.path.isdir(search_path):
+        if not os.path.exists(search_path):
+            raise FileNotFoundError(f"no such directory: {search_path}")
+        raise NotADirectoryError(f"not a directory: {search_path}")
+    guard = MountGuard(search_path, cross_mounts=cross_mounts)
+    min_bytes = int(min_mb * 1_048_576)
+
+    results: list[dict] = []
+    for dirpath, dirnames, filenames in os.walk(search_path):
+        try:
+            dir_dev = os.stat(dirpath).st_dev
+        except OSError:
+            dirnames[:] = []
+            continue
+        admitted = []
+        for name in dirnames:
+            sub = os.path.join(dirpath, name)
+            try:
+                sub_stat = os.lstat(sub)
+            except OSError:
+                continue
+            if stat.S_ISLNK(sub_stat.st_mode):
+                continue  # os.walk never follows a symlinked directory anyway
+            if guard.enter(sub, sub_stat.st_dev, dir_dev):
+                admitted.append(name)
+        dirnames[:] = admitted  # prune in place: os.walk descends only into these
+
+        for name in filenames:
+            fpath = os.path.join(dirpath, name)
+            try:
+                file_stat = os.stat(fpath, follow_symlinks=False)
+                if file_stat.st_size >= min_bytes:
+                    results.append(
+                        {
+                            "path": fpath,
+                            "size_mb": round(file_stat.st_size / 1_048_576, 2),
+                            "modified": datetime.fromtimestamp(file_stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+                        }
+                    )
+            except OSError:
+                continue
+
+    results.sort(key=lambda r: r["size_mb"], reverse=True)
+    report: dict = {"path": search_path, "min_mb": min_mb, "files": results[:limit], "match_count": len(results)}
+    if guard.skipped_mounts:
+        report["skipped_mounts"] = guard.skipped_mounts
+    return report
+
+
+def find_large_files(search_path: str, min_mb: float = 100.0, limit: int = 50, *, cross_mounts: bool = False) -> list[dict]:
+    """Return files under ``search_path`` at least ``min_mb`` MB, biggest first.
+
+    The ``files`` list of :func:`find_large_files_report`, with the same
+    filesystem boundary (one filesystem unless ``cross_mounts``; virtual
+    filesystems never) and the same errors for a bad ``search_path``.
+    """
+    return find_large_files_report(search_path, min_mb, limit, cross_mounts=cross_mounts)["files"]
+
+
+def backup_files(source: str, destination: str) -> dict:
+    """Create a timestamped ``.tar.gz`` of ``source`` inside ``destination``.
+
+    Returns the archive path and its size.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    source_name = Path(source).name or "backup"
+    archive_name = f"{source_name}_{timestamp}.tar.gz"
+    archive_path = os.path.join(destination, archive_name)
+
+    os.makedirs(destination, exist_ok=True)
+    with tarfile.open(archive_path, "w:gz") as tar:
+        tar.add(source, arcname=source_name)
+
+    size_bytes = os.path.getsize(archive_path)
+    return {
+        "source": source,
+        "destination": archive_path,
+        "size_bytes": size_bytes,
+        "size_mb": round(size_bytes / 1_048_576, 2),
+    }

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/runspec_linux_core/investigate.py

@@ -15,6 +15,7 @@ real tools.
 
 from __future__ import annotations
 
+import os
 import re
 import shutil
 import subprocess
@@ -153,12 +154,40 @@ def open_ports(proto: str = "tcp", *, run_as: str | None = None, become_method:
         check_become_error("open ports", result.stderr, run_as)
 
     rows = _parse_ss_listening(result.stdout)
-    out = {"proto": proto, "count": len(rows), "listeners": rows}
+    out: dict = {"proto": proto, "count": len(rows), "listeners": rows}
     if run_as:
         out["run_as"] = run_as
+    hint = _ports_hint(rows, run_as)
+    if hint:
+        out["hint"] = hint
     return out
 
 
+def _probe_is_root(run_as: str | None) -> bool:
+    if run_as:
+        return run_as == "root"
+    geteuid = getattr(os, "geteuid", None)
+    return geteuid is not None and geteuid() == 0
+
+
+def _ports_hint(rows: list[dict], run_as: str | None) -> str | None:
+    """Say so when owning processes are missing because the probe wasn't root.
+
+    ``ss -p`` only reports processes the caller may inspect, so an unprivileged
+    probe returns most listeners with an empty ``processes`` list — easy to
+    misread as "nothing owns this port" and to guess the owner from the number.
+    """
+    if _probe_is_root(run_as):
+        return None
+    missing = sum(1 for r in rows if not r["processes"])
+    if not missing:
+        return None
+    return (
+        f"{missing} of {len(rows)} listeners have no owning process because ss only shows other users' "
+        "processes to root — an empty list does not mean nothing owns the port. Re-run with --sudo to see them."
+    )
+
+
 def owning_package(path: str) -> dict:
     """Return which installed package owns ``path`` (dpkg on Debian/Ubuntu, rpm on
     RHEL/SUSE). Raises ToolNotFoundError if neither dpkg nor rpm is present;

{runspec_linux_core-0.7.0 → runspec_linux_core-0.9.0}/runspec_linux_core/network.py

@@ -2,13 +2,19 @@
 diagnostics (traceroute, route table, socket summary, DNS config) for tracing
 where an app's connectivity breaks."""
 
+import json
+import os
 import re
 import shutil
 import socket
 import subprocess
 import time
 
-from runspec_linux_core.errors import ToolNotFoundError
+from runspec_linux_core._paths import which
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+#: Where the kernel exposes per-interface attributes (speed, driver, device link).
+SYS_CLASS_NET = "/sys/class/net"
 
 
 def ping_host(host: str, count: int = 4) -> dict:
@@ -207,6 +213,75 @@ def route_table() -> dict:
     return {"routes": _parse_ip_route(result.stdout)}
 
 
+def network_interfaces(physical_only: bool = False) -> dict:
+    """List network interfaces (``ip -json address``): state, MAC address, MTU,
+    bridge/bond ``master`` and IPv4/IPv6 addresses, plus link speed and driver
+    for physical cards (from ``/sys/class/net``).
+
+    ``physical`` is true for an interface backed by a hardware device; loopback,
+    bridges, bonds, VLANs, veth pairs and tunnels are virtual. ``physical_only``
+    drops the virtual ones — container and Kubernetes hosts carry many veth links.
+    An address has ``dynamic: true`` when it came from DHCP or SLAAC.
+
+    Raises ToolNotFoundError if ``ip`` is not installed, CommandError if it fails.
+    """
+    ip = which("ip")
+    if not ip:
+        raise ToolNotFoundError("ip not available (iproute2)")
+    result = subprocess.run([ip, "-json", "address", "show"], capture_output=True, text=True)
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or f"ip exited {result.returncode}")
+    try:
+        links = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise CommandError(f"ip printed output that isn't JSON (iproute2 may be too old for -json): {exc}") from exc
+    # Some iproute2 versions emit empty objects in the list; skip anything unnamed.
+    interfaces = [_interface_row(link) for link in links if link.get("ifname")]
+    if physical_only:
+        interfaces = [row for row in interfaces if row["physical"]]
+    return {"interfaces": interfaces}
+
+
+def _sysfs_attr(name: str, attr: str) -> str | None:
+    try:
+        with open(os.path.join(SYS_CLASS_NET, name, attr)) as f:
+            return f.read().strip()
+    except OSError:
+        return None  # absent, or unreadable (speed raises EINVAL on a down link)
+
+
+def _interface_row(link: dict) -> dict:
+    name = link["ifname"]
+    physical = os.path.exists(os.path.join(SYS_CLASS_NET, name, "device"))
+    addresses = []
+    for addr in link.get("addr_info", []):
+        if not addr.get("local"):
+            continue
+        entry = {"family": addr.get("family"), "address": addr["local"], "prefix": addr.get("prefixlen"), "scope": addr.get("scope")}
+        if addr.get("dynamic"):
+            entry["dynamic"] = True
+        addresses.append(entry)
+    row: dict = {
+        "name": name,
+        "state": link.get("operstate"),
+        "physical": physical,
+        "type": link.get("link_type"),
+        "mac": link.get("address") if link.get("link_type") == "ether" else None,
+        "mtu": link.get("mtu"),
+        "master": link.get("master"),
+        "addresses": addresses,
+    }
+    if physical:
+        speed = _sysfs_attr(name, "speed")
+        mbps = int(speed) if speed and speed.lstrip("-").isdigit() else -1
+        row["speed_mbps"] = mbps if mbps > 0 else None  # the kernel reports -1 with no link
+        try:
+            row["driver"] = os.path.basename(os.readlink(os.path.join(SYS_CLASS_NET, name, "device", "driver")))
+        except OSError:
+            row["driver"] = None
+    return {key: value for key, value in row.items() if value is not None}
+
+
 def _parse_ss_summary(output: str) -> dict:
     """Parse ``ss -s`` summary output into ``{total, tcp: {...}, ...}``."""
     summary: dict = {}