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

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

@@ -1,5 +1,24 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runspec-linux-core
-Version: 0.8.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.8.0 → runspec_linux_core-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.8.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.8.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.8.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.8.0 → runspec_linux_core-0.9.0}/tests/test_containers_runas.py

@@ -66,3 +66,39 @@ def test_restart_container_run_as_passwordless_hint(monkeypatch: pytest.MonkeyPa
     _stub(monkeypatch, rc=1, stderr="sudo: a terminal is required")
     with pytest.raises(Exception, match="passwordless sudo is not configured for run-as 'svc'"):
         containers.restart_container("web", run_as="svc")
+
+
+_SOCKET_DENIED = "permission denied while trying to connect to the docker API at unix:///var/run/docker.sock"
+
+
+def test_list_containers_socket_denied_suggests_sudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr=_SOCKET_DENIED)
+    with pytest.raises(containers.CommandError, match="Re-run with --sudo") as err:
+        containers.list_containers(include_all=True)
+    assert "docker.sock" in str(err.value)
+
+
+def test_container_logs_socket_denied_is_an_error_not_log_lines(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr=_SOCKET_DENIED)
+    with pytest.raises(containers.CommandError, match="--sudo"):
+        containers.container_logs("web")
+
+
+def test_container_logs_other_failure_still_returned_as_lines(monkeypatch: pytest.MonkeyPatch) -> None:
+    # unchanged: an unescalated non-permission failure keeps the old behaviour
+    _stub(monkeypatch, rc=1, stderr="Error: No such container: web")
+    assert containers.container_logs("web")["lines"] == ["Error: No such container: web"]
+
+
+def test_restart_container_socket_denied_suggests_sudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub(monkeypatch, rc=1, stderr=_SOCKET_DENIED)
+    with pytest.raises(containers.CommandError, match="docker group"):
+        containers.restart_container("web")
+
+
+def test_escalated_socket_denied_keeps_the_generic_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    # escalated already → "re-run with --sudo" would be wrong advice
+    _stub(monkeypatch, rc=1, stderr=_SOCKET_DENIED)
+    with pytest.raises(containers.CommandError) as err:
+        containers.list_containers(run_as="deploy")
+    assert "--sudo" not in str(err.value)

{runspec_linux_core-0.8.0 → runspec_linux_core-0.9.0}/tests/test_investigate.py

@@ -84,3 +84,40 @@ def test_owning_package_dpkg(monkeypatch: pytest.MonkeyPatch) -> None:
     )
     out = investigate.owning_package("/usr/bin/ls")
     assert out == {"path": "/usr/bin/ls", "owned": True, "package": "coreutils", "manager": "dpkg"}
+
+
+_SS_MIXED = (
+    "State  Recv-Q Send-Q Local Address:Port Peer Address:Port Process\n"
+    "LISTEN 0      511    0.0.0.0:80         0.0.0.0:*\n"
+    "LISTEN 0      128    0.0.0.0:22         0.0.0.0:*\n"
+    'LISTEN 0      128    127.0.0.1:8765     0.0.0.0:*         users:(("console-room",pid=991,fd=5))\n'
+)
+
+
+def _stub_ss(monkeypatch: pytest.MonkeyPatch, stdout: str) -> None:
+    monkeypatch.setattr(investigate.shutil, "which", lambda _: "/usr/bin/ss")
+    monkeypatch.setattr(investigate.subprocess, "run", lambda argv, **kw: subprocess.CompletedProcess(argv, 0, stdout=stdout, stderr=""))
+
+
+def test_open_ports_hints_when_unprivileged_probe_misses_owners(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub_ss(monkeypatch, _SS_MIXED)
+    monkeypatch.setattr(investigate.os, "geteuid", lambda: 1000, raising=False)
+    out = investigate.open_ports("tcp")
+    assert out["hint"].startswith("2 of 3 listeners have no owning process")
+    assert "--sudo" in out["hint"]
+
+
+def test_open_ports_no_hint_as_root_or_escalated(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub_ss(monkeypatch, _SS_MIXED)
+    monkeypatch.setattr(investigate.os, "geteuid", lambda: 0, raising=False)
+    assert "hint" not in investigate.open_ports("tcp")
+    monkeypatch.setattr(investigate.os, "geteuid", lambda: 1000, raising=False)
+    assert "hint" not in investigate.open_ports("tcp", run_as="root")
+    # escalating to a non-root user still can't see everyone's processes
+    assert "hint" in investigate.open_ports("tcp", run_as="deploy")
+
+
+def test_open_ports_no_hint_when_every_owner_is_known(monkeypatch: pytest.MonkeyPatch) -> None:
+    _stub_ss(monkeypatch, 'State Recv-Q Send-Q Local Peer Process\nLISTEN 0 1 127.0.0.1:8765 0.0.0.0:* users:(("console-room",pid=991,fd=5))\n')
+    monkeypatch.setattr(investigate.os, "geteuid", lambda: 1000, raising=False)
+    assert "hint" not in investigate.open_ports("tcp")