runspec-linux-core 0.2.0__tar.gz → 0.3.0__tar.gz

{runspec_linux_core-0.2.0 → runspec_linux_core-0.3.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # runspec-linux-core Changelog
 
+## [0.3.0] — 2026-06-20
+
+Add `enable_passwordless_sudo()` (new `sudoers.py`) — the one-time bootstrap that
+makes the `run_as = "root"` package/power runnables work without a password.
+
+- Installs a validated drop-in at `/etc/sudoers.d/runspec`. Two scopes:
+  `"scoped"` → `NOPASSWD` for the runspec venv's runnable scripts only
+  (`{venv_bin}/`); `"all"` → `NOPASSWD: ALL`.
+- The sudo password is read from **stdin via `sudo -S`** — never on argv, in the
+  process table, shell history, or the audit log.
+- Validates with `visudo -cf` before install *and* `visudo -c` after; rolls the
+  drop-in back if the post-install check fails, so a typo can't lock sudo out.
+- The target user name is validated against a strict pattern before it reaches
+  the file (no rule injection); idempotent when an identical drop-in exists.
+- Raises `ValueError` (bad scope/user), `ToolNotFoundError` (no `sudo`/`visudo`),
+  or `CommandError` (auth failure / validation failure).
+
+Note: the console's *agent* path wraps the command in `env(1)`, so a `"scoped"`
+grant covers manual/CLI runs; agent-driven runs need `"all"`.
+
 ## [0.2.0] — 2026-06-20
 
 Add package-manager and host-power helpers so a fleet can be patched and

{runspec_linux_core-0.2.0 → runspec_linux_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.2.0
+Version: 0.3.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.2.0 → runspec_linux_core-0.3.0}/pyproject.toml

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

@@ -30,6 +30,7 @@ from runspec_linux_core.packages import (
 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
 
 __all__ = [
@@ -73,6 +74,8 @@ __all__ = [
     "remove_package",
     # power
     "reboot_host",
+    # sudoers
+    "enable_passwordless_sudo",
     # tcp
     "nc_send",
 ]

runspec_linux_core-0.3.0/runspec_linux_core/sudoers.py

@@ -0,0 +1,129 @@
+"""Bootstrap passwordless sudo so the console's ``run_as = "root"`` path works.
+
+This is the one-time, interactive complement to ``run_as``: the operator supplies
+their sudo password (delivered out of band by the caller — never on argv) and we
+install a **validated** drop-in under ``/etc/sudoers.d`` so subsequent
+``run_as = "root"`` invocations escalate without a password.
+
+The password is read from stdin via ``sudo -S`` — it never appears in argv, the
+process table, shell history, or the audit log. The drop-in is validated with
+``visudo`` before *and* after install, and rolled back if the post-install check
+fails, so a typo can't lock the operator out of sudo.
+
+Two grant scopes:
+
+- ``"scoped"`` — ``NOPASSWD`` only for the runspec venv's runnable scripts
+  (``{venv_bin}/``). Least privilege, and enough for **manual** console runs and
+  direct CLI/cron. Note: the console's *agent* path wraps the command in
+  ``env(1)`` to carry ``RUNSPEC_AGENT`` through sudo, so under the agent the
+  command sudo sees is ``/usr/bin/env …`` — which this scope does **not** match.
+  Agent-driven fleet management therefore needs ``"all"``.
+- ``"all"`` — ``NOPASSWD: ALL``. Works for every path (manual *and* agent).
+"""
+
+import getpass
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+_DROP_IN = "/etc/sudoers.d/runspec"
+_MANAGED_HEADER = "# Managed by runspec-linux enable-passwordless-sudo\n"
+
+# POSIX-ish user/group name: starts with a letter or underscore, then letters,
+# digits, _, -, . and an optional trailing $ (machine accounts). Validated before
+# interpolation into the sudoers file so a crafted name can't inject extra rules.
+_USER_RE = re.compile(r"^[a-z_][a-z0-9_.-]*\$?$")
+
+
+def _runspec_bin_dir() -> str:
+    """The venv bin directory holding the runspec runnable scripts.
+
+    The console invokes a runnable as ``{bin_dir}/{runnable}``; on a standard
+    venv install that is the directory of the running interpreter (kept as the
+    venv path, not resolved through symlinks).
+    """
+    return os.path.dirname(sys.executable)
+
+
+def _sudoers_content(user: str, scope: str, bin_dir: str) -> str:
+    # scoped: a trailing slash matches any command in the runspec venv bin dir.
+    rule = f"{user} ALL=(ALL) NOPASSWD: ALL" if scope == "all" else f"{user} ALL=(root) NOPASSWD: {bin_dir}/"
+    return f"{_MANAGED_HEADER}{rule}\n"
+
+
+def _sudo(password: str, argv: list[str]) -> subprocess.CompletedProcess:
+    """Run ``sudo -S -p '' argv``, feeding ``password`` on stdin (never on argv)."""
+    return subprocess.run(
+        ["sudo", "-S", "-p", "", *argv],
+        input=password + "\n",
+        capture_output=True,
+        text=True,
+    )
+
+
+def _auth_hint(result: subprocess.CompletedProcess) -> str:
+    err = result.stderr.strip()
+    low = err.lower()
+    if "incorrect password" in low or "try again" in low or "authentication failure" in low:
+        return "sudo authentication failed — check the password"
+    return err or "sudo command failed"
+
+
+def enable_passwordless_sudo(password: str, user: str | None = None, scope: str = "scoped") -> dict:
+    """Install a validated ``/etc/sudoers.d/runspec`` granting passwordless sudo.
+
+    ``user`` defaults to the current login user. ``scope`` is ``"scoped"`` (the
+    runspec venv runnables only) or ``"all"`` (``NOPASSWD: ALL``). Returns
+    ``{user, scope, path, installed: True, already_configured}``.
+
+    Raises ValueError on a bad scope/user, ToolNotFoundError if sudo/visudo are
+    missing, or CommandError on a sudo auth failure or a sudoers validation
+    failure (in which case the drop-in is rolled back).
+    """
+    if scope not in ("scoped", "all"):
+        raise ValueError(f"invalid scope: {scope!r} (expected 'scoped' or 'all')")
+    user = user or getpass.getuser()
+    if not _USER_RE.match(user):
+        raise ValueError(f"invalid user name: {user!r}")
+    if not shutil.which("sudo"):
+        raise ToolNotFoundError("sudo is not installed")
+    if not shutil.which("visudo"):
+        raise ToolNotFoundError("visudo is not installed (needed to validate the sudoers file)")
+
+    content = _sudoers_content(user, scope, _runspec_bin_dir())
+
+    with tempfile.NamedTemporaryFile("w", suffix=".sudoers", delete=False) as tf:
+        tf.write(content)
+        tmp_path = tf.name
+    try:
+        # 1) Validate the generated syntax locally before touching the system.
+        check = subprocess.run(["visudo", "-cf", tmp_path], capture_output=True, text=True)
+        if check.returncode != 0:
+            detail = check.stdout.strip() or check.stderr.strip()
+            raise CommandError(f"generated sudoers failed validation: {detail}")
+
+        # 2) Idempotent: identical drop-in already present? (reading it needs root)
+        existing = _sudo(password, ["cat", _DROP_IN])
+        if existing.returncode == 0 and existing.stdout == content:
+            return {"user": user, "scope": scope, "path": _DROP_IN, "installed": True, "already_configured": True}
+
+        # 3) Install atomically as root, 0440 root:root.
+        install = _sudo(password, ["install", "-m", "0440", "-o", "root", "-g", "root", tmp_path, _DROP_IN])
+        if install.returncode != 0:
+            raise CommandError(_auth_hint(install))
+
+        # 4) Re-validate the whole sudoers tree; roll our drop-in back if broken.
+        verify = _sudo(password, ["visudo", "-c"])
+        if verify.returncode != 0:
+            _sudo(password, ["rm", "-f", _DROP_IN])
+            detail = verify.stdout.strip() or verify.stderr.strip()
+            raise CommandError(f"sudoers validation failed after install — rolled back: {detail}")
+
+        return {"user": user, "scope": scope, "path": _DROP_IN, "installed": True, "already_configured": False}
+    finally:
+        os.unlink(tmp_path)

{runspec_linux_core-0.2.0 → runspec_linux_core-0.3.0}/tests/test_preconditions.py

@@ -104,3 +104,9 @@ def test_reboot_host_requires_a_tool(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr("runspec_linux_core.power.shutil.which", lambda _: None)
     with pytest.raises(ToolNotFoundError):
         core.reboot_host()
+
+
+def test_enable_passwordless_sudo_requires_sudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda _: None)
+    with pytest.raises(ToolNotFoundError):
+        core.enable_passwordless_sudo("pw", "alice", "scoped")

runspec_linux_core-0.3.0/tests/test_sudoers.py

@@ -0,0 +1,147 @@
+"""enable_passwordless_sudo: content generation, validation, install + rollback.
+
+No real sudo/visudo is invoked — the subprocess layer is stubbed so the control
+flow (pre-validate, idempotency, install, post-validate, rollback) is exercised
+deterministically. The password is asserted to travel via stdin, never argv.
+"""
+
+import subprocess
+
+import pytest
+
+from runspec_linux_core import sudoers
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+
+def _ok(stdout: str = "", returncode: int = 0, stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+@pytest.fixture(autouse=True)
+def _tools_present(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda name: f"/usr/sbin/{name}")
+    monkeypatch.setattr("runspec_linux_core.sudoers._runspec_bin_dir", lambda: "/opt/rs/bin")
+
+
+# ── content ───────────────────────────────────────────────────────────────────
+
+
+def test_scoped_content_targets_venv_bin() -> None:
+    out = sudoers._sudoers_content("alice", "scoped", "/opt/rs/bin")
+    assert "alice ALL=(root) NOPASSWD: /opt/rs/bin/\n" in out
+    assert out.startswith("# Managed by runspec-linux")
+
+
+def test_all_content_is_nopasswd_all() -> None:
+    out = sudoers._sudoers_content("alice", "all", "/opt/rs/bin")
+    assert "alice ALL=(ALL) NOPASSWD: ALL\n" in out
+
+
+# ── input validation ──────────────────────────────────────────────────────────
+
+
+def test_rejects_bad_scope() -> None:
+    with pytest.raises(ValueError):
+        sudoers.enable_passwordless_sudo("pw", "alice", "everything")
+
+
+@pytest.mark.parametrize("bad", ["root\nbad ALL=(ALL) NOPASSWD: ALL", "al ice", "-x", "a;b"])
+def test_rejects_injection_in_user(bad: str) -> None:
+    with pytest.raises(ValueError):
+        sudoers.enable_passwordless_sudo("pw", bad, "scoped")
+
+
+# ── install flow ──────────────────────────────────────────────────────────────
+
+
+def test_install_happy_path_pipes_password_via_stdin(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[dict] = []
+
+    def fake_run(cmd, **kw):
+        calls.append({"cmd": cmd, "input": kw.get("input")})
+        if cmd[:2] == ["visudo", "-cf"]:  # local pre-validate
+            return _ok()
+        if cmd[:4] == ["sudo", "-S", "-p", ""]:
+            sub = cmd[4:]  # args after the `sudo -S -p ''` prefix
+            if sub[0] == "cat":  # idempotency probe: not yet installed
+                return _ok(returncode=1, stderr="No such file")
+            if sub[0] == "install":
+                return _ok()
+            if sub[0] == "visudo":  # post-validate
+                return _ok()
+        raise AssertionError(f"unexpected command: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+
+    result = sudoers.enable_passwordless_sudo("s3cret", "alice", "all")
+    assert result == {
+        "user": "alice",
+        "scope": "all",
+        "path": "/etc/sudoers.d/runspec",
+        "installed": True,
+        "already_configured": False,
+    }
+    # Password rides stdin on every sudo call — never appears in any argv.
+    sudo_calls = [c for c in calls if c["cmd"][:1] == ["sudo"]]
+    assert sudo_calls and all(c["input"] == "s3cret\n" for c in sudo_calls)
+    assert not any("s3cret" in " ".join(c["cmd"]) for c in calls)
+
+
+def test_idempotent_when_identical_drop_in_exists(monkeypatch: pytest.MonkeyPatch) -> None:
+    content = sudoers._sudoers_content("alice", "all", "/opt/rs/bin")
+
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        if cmd[4:5] == ["cat"]:
+            return _ok(stdout=content)  # already present, identical
+        raise AssertionError(f"should not install: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    result = sudoers.enable_passwordless_sudo("pw", "alice", "all")
+    assert result["already_configured"] is True
+
+
+def test_wrong_password_raises_command_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        if cmd[4:5] == ["cat"]:
+            return _ok(returncode=1)
+        if cmd[4:5] == ["install"]:
+            return _ok(returncode=1, stderr="sudo: 1 incorrect password attempt")
+        raise AssertionError(f"unexpected: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    with pytest.raises(CommandError, match="authentication failed"):
+        sudoers.enable_passwordless_sudo("wrong", "alice", "all")
+
+
+def test_post_validate_failure_rolls_back(monkeypatch: pytest.MonkeyPatch) -> None:
+    removed: list[list[str]] = []
+
+    def fake_run(cmd, **kw):
+        if cmd[:2] == ["visudo", "-cf"]:
+            return _ok()
+        sub = cmd[4:] if cmd[:4] == ["sudo", "-S", "-p", ""] else []
+        if sub[:1] == ["cat"]:
+            return _ok(returncode=1)
+        if sub[:1] == ["install"]:
+            return _ok()
+        if sub[:1] == ["visudo"]:  # whole-tree check fails
+            return _ok(returncode=1, stderr=">>> syntax error")
+        if sub[:1] == ["rm"]:
+            removed.append(sub)
+            return _ok()
+        raise AssertionError(f"unexpected: {cmd}")
+
+    monkeypatch.setattr("runspec_linux_core.sudoers.subprocess.run", fake_run)
+    with pytest.raises(CommandError, match="rolled back"):
+        sudoers.enable_passwordless_sudo("pw", "alice", "scoped")
+    assert removed and removed[0] == ["rm", "-f", "/etc/sudoers.d/runspec"]
+
+
+def test_requires_visudo(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("runspec_linux_core.sudoers.shutil.which", lambda name: None if name == "visudo" else "/usr/bin/sudo")
+    with pytest.raises(ToolNotFoundError, match="visudo"):
+        sudoers.enable_passwordless_sudo("pw", "alice", "scoped")