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

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

@@ -1,5 +1,38 @@
 # runspec-linux-core Changelog
 
+## [0.7.0] — 2026-09-25
+
+### Added
+
+- **`share_venv_logs(venv, *, group=None, run_as=None, become_method="sudo")`** —
+  the repair path for a venv **not** built by `create-venv --group` (hand-made or
+  legacy). Sets `<venv>/logs` to `2775` (setgid + group-writable) so new files —
+  including the per-venv runs index `runspec_runs.db` and the audit-log files —
+  inherit the directory's group and can be written across a shared console group,
+  and, with `group`, `chgrp`s the `logs/` **directory** to it. The chgrp is on the
+  directory only (not `-R`): `logs/` already holds per-run files owned by *other*
+  users (a `run_as="root"` runnable leaves root-owned logs there) which a non-root
+  caller can't chgrp, and the setgid bit means only new files need the group. This
+  is exactly what `create_venv` does at build time, applied to an existing venv
+  without recreating it. Raises `ValueError` for a bad group name or a `<venv>`
+  that isn't a directory, `CommandError` on a failed step. Backs the new
+  `share-venv-logs` runnable in `runspec-linux`.
+
+### Fixed
+
+- **`install_into_venv` regression (0.6.1): `chmod: … Operation not permitted` on
+  a `--symlinks` venv's `bin/python*`.** 0.6.1 replaced the `chmod -R` normalise
+  sweep with `find … -exec chmod {} +` to prune the `logs/` dir. But `find -exec
+  chmod` **dereferences a symlink argument**, and a venv built with `--symlinks`
+  (what `create_venv` always does) has `bin/python`, `bin/python3`,
+  `bin/python3.X` pointing at the **root-owned system interpreter outside the
+  venv** — so the sweep tried to `chmod /usr/bin/python3.X` and failed for a
+  non-root caller (or, under sudo, would have silently repermissioned the system
+  Python). `chmod -R` skipped symlinks for free; the `find` sweep now prunes them
+  explicitly too (`-type l -prune`), matching the old behaviour. A symlink's own
+  mode is unused on Linux, so nothing is lost. The `logs/` prune from 0.6.1 is
+  unchanged. No API change.
+
 ## [0.6.1] — 2026-09-17
 
 ### Fixed

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.6.1"
+version = "0.7.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.6.1 → runspec_linux_core-0.7.0}/runspec_linux_core/__init__.py

@@ -63,7 +63,7 @@ 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.venvs import configure_pip, create_venv, install_into_venv
+from runspec_linux_core.venvs import configure_pip, create_venv, install_into_venv, share_venv_logs
 
 __all__ = [
     # errors
@@ -139,6 +139,7 @@ __all__ = [
     "create_venv",
     "install_into_venv",
     "configure_pip",
+    "share_venv_logs",
     # tcp
     "nc_send",
     # commands

{runspec_linux_core-0.6.1 → runspec_linux_core-0.7.0}/runspec_linux_core/venvs.py

@@ -115,6 +115,54 @@ def create_venv(
     }
 
 
+def share_venv_logs(
+    venv: str,
+    *,
+    group: str | None = None,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+) -> dict:
+    """Make an existing venv's ``logs/`` dir shared — the repair path for a venv
+    **not** built by ``create-venv --group`` (hand-made or legacy).
+
+    Sets ``<venv>/logs`` to ``2775`` (setgid + group-writable) so new files —
+    including the per-venv runs index ``runspec_runs.db`` and the audit-log
+    files — inherit the directory's group and can be written by every console /
+    service account in a shared group. When ``group`` is given it also
+    ``chgrp``s the ``logs/`` **directory** to it.
+
+    The chgrp is on the directory only, **not** ``-R``: ``logs/`` already holds
+    per-run files owned by *other* users (a ``run_as="root"`` runnable leaves
+    root-owned logs there), which a non-root caller can't chgrp — and the setgid
+    bit means only *new* files need the group anyway (the DB is created fresh).
+    ``create-venv --group`` does exactly this at build time; this brings a
+    pre-existing venv up to the same state without recreating it. With
+    ``run_as`` every step runs as that user (the venv's owner).
+
+    Raises ValueError if ``group`` is malformed or ``<venv>`` isn't an existing
+    directory, CommandError on a failed step.
+    """
+    if group is not None:
+        _validate_name(group, "group")
+    if not _dir_exists_as(venv, run_as, become_method):
+        raise ValueError(f"not a directory: {venv!r} (point at an existing venv)")
+
+    logs_dir = os.path.join(venv, "logs")
+    _check(_run(build_become(["mkdir", "-p", logs_dir], run_as, become_method)), "logs dir", run_as)
+    if group:
+        _check(_run(build_become(["chgrp", group, logs_dir], run_as, become_method)), "chgrp logs", run_as)
+    _check(_run(build_become(["chmod", "2775", logs_dir], run_as, become_method)), "chmod logs", run_as)
+
+    return {
+        "venv": venv,
+        "logs_dir": logs_dir,
+        "group": group or "",
+        "run_as": run_as or "",
+        "mode": "2775",
+        "shared": True,
+    }
+
+
 def install_into_venv(
     venv: str,
     packages: str = "",
@@ -140,11 +188,15 @@ def install_into_venv(
     regardless of the caller's umask — a ``sudo`` upgrade under a PAM-set ``027``
     login umask otherwise lands site-packages entries at ``750`` and hides the
     packs from ``runspec local`` / ``importlib.metadata`` for anyone but the
-    owner. The sweep **prunes** ``<venv>/logs``: it is the group-shared audit dir
-    and holds per-run log files owned by other users (a ``run_as="root"`` runnable
-    leaves root-owned logs there), so a blanket ``chmod`` as a non-root caller
-    would fail with "Operation not permitted". Its ``2775`` setgid mode is left
-    intact, and restored afterwards as a guard if the dir exists.
+    owner. The sweep **prunes** two things: ``<venv>/logs`` (the group-shared
+    audit dir, which holds per-run log files owned by other users — a
+    ``run_as="root"`` runnable leaves root-owned logs there — so its ``2775``
+    setgid mode is left intact and restored afterwards as a guard), and
+    **symlinks** (a ``--symlinks`` venv's ``bin/python*`` point at the root-owned
+    system interpreter *outside* the venv; ``find -exec chmod`` would dereference
+    them and fail — or, under sudo, silently repermission the system Python —
+    where ``chmod -R`` skipped symlinks for free). A symlink's own mode is unused
+    on Linux, so pruning them changes nothing.
     """
     from runspec_linux_core.packages import _validate_packages
 
@@ -179,17 +231,40 @@ def install_into_venv(
     # Normalise pip's freshly-created site-packages entries to u=rwX,go=rX (the
     # same step create_venv runs) so a sudo install under a restrictive login
     # umask can't land them at 750 and hide the packs from `runspec local` /
-    # importlib.metadata. Prune <venv>/logs from the sweep: it is the group-shared
-    # (2775) audit dir and accrues per-run log files owned by *other* users — a
-    # run_as="root" runnable (list-upgrades / upgrade-packages) leaves root-owned
-    # logs there, so a blanket `chmod -R` as a non-root caller dies with
-    # "Operation not permitted" on them. `find ... -prune` skips that subtree; its
-    # own 2775 mode is left intact (and restored below as a belt-and-braces guard).
+    # importlib.metadata. Two subtrees are pruned:
+    #   * <venv>/logs — the group-shared (2775) audit dir, which accrues per-run
+    #     log files owned by *other* users (a run_as="root" runnable such as
+    #     list-upgrades / upgrade-packages leaves root-owned logs there), so a
+    #     non-root caller's chmod on them dies with "Operation not permitted".
+    #   * symlinks (-type l) — a `--symlinks` venv's bin/python* point at the
+    #     system interpreter (root-owned, *outside* the venv). `find -exec chmod`
+    #     dereferences a symlink argument, so without this it would chmod the
+    #     system python: "Operation not permitted" as a normal user, or a silent
+    #     repermission of /usr/bin/python* under sudo. `chmod -R` skipped symlinks
+    #     for free; the find sweep must skip them explicitly to match. A symlink's
+    #     own mode is irrelevant on Linux, so nothing is lost.
+    # The logs dir keeps its 2775 mode (restored below as a belt-and-braces guard).
     logs_dir = os.path.join(venv, "logs")
     _check(
         _run(
             build_become(
-                ["find", venv, "-path", logs_dir, "-prune", "-o", "-exec", "chmod", "u=rwX,go=rX", "{}", "+"],
+                [
+                    "find",
+                    venv,
+                    "-path",
+                    logs_dir,
+                    "-prune",
+                    "-o",
+                    "-type",
+                    "l",
+                    "-prune",
+                    "-o",
+                    "-exec",
+                    "chmod",
+                    "u=rwX,go=rX",
+                    "{}",
+                    "+",
+                ],
                 run_as,
                 become_method,
             )
@@ -317,3 +392,8 @@ def configure_pip(
 def _path_exists_as(path: str, run_as: str | None, become_method: str) -> bool:
     """True if ``path`` exists from the run-as user's view (``test -e``)."""
     return _run(build_become(["test", "-e", path], run_as, become_method)).returncode == 0
+
+
+def _dir_exists_as(path: str, run_as: str | None, become_method: str) -> bool:
+    """True if ``path`` is a directory from the run-as user's view (``test -d``)."""
+    return _run(build_become(["test", "-d", path], run_as, become_method)).returncode == 0

{runspec_linux_core-0.6.1 → runspec_linux_core-0.7.0}/tests/test_venvs.py

@@ -101,6 +101,93 @@ def test_create_venv_raises_on_failure(monkeypatch: pytest.MonkeyPatch) -> None:
         venvs.create_venv(sys.executable, "/opt/v1")
 
 
+# ── share_venv_logs (repair a legacy venv's logs/ perms) ───────────────────────
+
+
+def test_share_venv_logs_builds_commands(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)  # default stub: `test -d` returns 0
+
+    result = venvs.share_venv_logs("/opt/v1")
+
+    # Verify the venv is a dir, then mkdir -p logs, then chmod 2775 logs. No chgrp
+    # without a group; the chmod is the last step.
+    assert calls == [
+        ["test", "-d", "/opt/v1"],
+        ["mkdir", "-p", "/opt/v1/logs"],
+        ["chmod", "2775", "/opt/v1/logs"],
+    ]
+    assert result == {
+        "venv": "/opt/v1",
+        "logs_dir": "/opt/v1/logs",
+        "group": "",
+        "run_as": "",
+        "mode": "2775",
+        "shared": True,
+    }
+
+
+def test_share_venv_logs_with_group_chgrps_dir_only(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+
+    venvs.share_venv_logs("/opt/v1", group="consoles")
+
+    # chgrp targets the logs *directory* only — never `-R` (logs/ holds per-run
+    # files owned by other users a non-root caller can't chgrp; setgid covers new
+    # files). Order: test -d, mkdir, chgrp, chmod.
+    assert calls == [
+        ["test", "-d", "/opt/v1"],
+        ["mkdir", "-p", "/opt/v1/logs"],
+        ["chgrp", "consoles", "/opt/v1/logs"],
+        ["chmod", "2775", "/opt/v1/logs"],
+    ]
+    assert not any(c[:2] == ["chgrp", "-R"] for c in calls)
+
+
+def test_share_venv_logs_run_as_escalates_every_step(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+
+    venvs.share_venv_logs("/opt/v1", group="consoles", run_as="svc")
+
+    for cmd in calls:
+        assert cmd[:4] == ["sudo", "-n", "-u", "svc"]
+    assert ["sudo", "-n", "-u", "svc", "chgrp", "consoles", "/opt/v1/logs"] in calls
+    assert ["sudo", "-n", "-u", "svc", "chmod", "2775", "/opt/v1/logs"] in calls
+
+
+def test_share_venv_logs_rejects_missing_venv(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[list[str]] = []
+
+    def fake_run(argv: list[str]) -> subprocess.CompletedProcess:
+        calls.append(argv)
+        return _completed(returncode=1)  # `test -d` fails → not a directory
+
+    monkeypatch.setattr(venvs, "_run", fake_run)
+
+    with pytest.raises(ValueError):
+        venvs.share_venv_logs("/opt/nope")
+    # Bailed after the probe — no mkdir/chmod attempted.
+    assert calls == [["test", "-d", "/opt/nope"]]
+
+
+def test_share_venv_logs_rejects_bad_group(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.share_venv_logs("/opt/v1", group="bad group")
+    # Group is validated before any subprocess runs (not even the `test -d` probe).
+    assert calls == []
+
+
+def test_share_venv_logs_raises_on_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_run(argv: list[str]) -> subprocess.CompletedProcess:
+        if argv[:2] == ["test", "-d"]:
+            return _completed(returncode=0)  # dir exists…
+        return _completed("", returncode=1, stderr="boom")  # …but a step fails
+
+    monkeypatch.setattr(venvs, "_run", fake_run)
+    with pytest.raises(CommandError):
+        venvs.share_venv_logs("/opt/v1")
+
+
 # ── install_into_venv ─────────────────────────────────────────────────────────
 
 
@@ -148,9 +235,11 @@ def test_install_into_venv_normalises_perms(tmp_path, monkeypatch: pytest.Monkey
 
     venvs.install_into_venv(venv, "httpx", upgrade=True, run_as="svc")
 
-    # The normalise sweep prunes <venv>/logs so a non-root caller never chmods the
-    # root-owned per-run log files a run_as="root" runnable leaves there
-    # (otherwise: chmod "Operation not permitted", and the install reports failure).
+    # The normalise sweep prunes <venv>/logs (root-owned per-run logs a
+    # run_as="root" runnable leaves there) AND symlinks (a --symlinks venv's
+    # bin/python* point at the root-owned system interpreter; find -exec chmod
+    # would dereference and fail / repermission it). Otherwise: chmod "Operation
+    # not permitted", and the install reports failure.
     assert [
         "sudo",
         "-n",
@@ -162,6 +251,10 @@ def test_install_into_venv_normalises_perms(tmp_path, monkeypatch: pytest.Monkey
         f"{venv}/logs",
         "-prune",
         "-o",
+        "-type",
+        "l",
+        "-prune",
+        "-o",
         "-exec",
         "chmod",
         "u=rwX,go=rX",
@@ -198,7 +291,23 @@ def test_install_into_venv_skips_logs_restore_when_absent(tmp_path, monkeypatch:
 
     venvs.install_into_venv(venv, "httpx")
 
-    assert ["find", venv, "-path", f"{venv}/logs", "-prune", "-o", "-exec", "chmod", "u=rwX,go=rX", "{}", "+"] in calls
+    assert [
+        "find",
+        venv,
+        "-path",
+        f"{venv}/logs",
+        "-prune",
+        "-o",
+        "-type",
+        "l",
+        "-prune",
+        "-o",
+        "-exec",
+        "chmod",
+        "u=rwX,go=rX",
+        "{}",
+        "+",
+    ] in calls
     assert ["test", "-d", f"{venv}/logs"] in calls
     assert not any(c[:2] == ["chmod", "2775"] for c in calls)