runspec-linux-core 0.3.4__tar.gz → 0.4.0__tar.gz

{runspec_linux_core-0.3.4 → runspec_linux_core-0.4.0}/CHANGELOG.md

@@ -1,5 +1,53 @@
 # runspec-linux-core Changelog
 
+## [0.4.0] — 2026-08-01
+
+New shared privilege-escalation module `runspec_linux_core.become` — the single
+source of truth for runspec-linux's per-invocation `run_as` escalation
+(mechanism B). It exposes `build_become(argv, run_as, method)` (`sudo -n -u` /
+`su -c`), `validate_user`, `check_become_error` (the passwordless-sudo hint),
+`escalation_supported`, `current_user`, and `BecomeError` (a `CommandError`).
+`venvs.py` now delegates to it instead of its own private `_become`/`_check`
+copy — byte-identical command output, no behaviour change beyond invalid
+run-as/method now raising `BecomeError` (a `CommandError`) rather than a bare
+`ValueError`. This module also backs the new `--run-as` / `--sudo` mutually
+exclusive args on the privileged `runspec-linux` runnables.
+
+New system-admin helpers for corporate app-support and performance work:
+
+- `perf.py` — `get_sysctl` / `set_sysctl` (read/tune kernel params, optional
+  `/etc/sysctl.d` persist), `cpu_info` (governor/frequency/topology),
+  `pressure` (PSI `/proc/pressure/*`).
+- `investigate.py` — `service_detail` (a unit's ExecStart/env/paths/state),
+  `open_ports` (listening port → pid → process), `owning_package` (which
+  package owns a path, dpkg/rpm), `failed_units` (`systemctl --failed`).
+- `network.py` additions — `trace_route`, `route_table`, `socket_stats`,
+  `dns_config`.
+
+The privileged helpers (`set_sysctl` persist, `service_detail`, `open_ports`,
+and the log/service helpers) take `run_as` / `become_method` params and wrap
+their subprocesses with `build_become`, so a caller can run them as root or a
+specific service account.
+
+## [0.3.5] — 2026-07-08
+
+Apply the same umask-neutralising treatment to `install_into_venv` that `0.3.4`
+added to `create_venv`. After the `pip install`, the venv tree is now
+normalised with `chmod -R u=rwX,go=rX <venv>` so pip's new directories are
+`755` regardless of the caller's umask.
+
+The trigger was a `sudo pip install --upgrade runspec-linux` under a host
+where sudo/PAM had switched to a `027` login umask: pip's new
+`site-packages/runspec_linux/` and `site-packages/runspec_linux_core/`
+directories landed at `750`, and `runspec local` (walking `.dist-info` via
+`importlib.metadata`) stopped seeing the packs for any user but the owner.
+The equivalent bug for the venv root was fixed at build time in `0.3.4`; this
+release closes the same gap at upgrade time.
+
+If `<venv>/logs` exists (created by `create_venv`), its `2775` setgid mode is
+restored after the wide chmod — the `test -d` guard skips the restore for a
+venv built some other way. When `run_as` is set the new steps escalate too.
+
 ## [0.3.4] — 2026-07-07
 
 Fix `create_venv` producing an unreadable `750` venv directory when the caller's

{runspec_linux_core-0.3.4 → runspec_linux_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.3.4
+Version: 0.4.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.3.4 → runspec_linux_core-0.4.0}/pyproject.toml

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

@@ -9,6 +9,14 @@ Each function does the work and returns plain data; failures raise (see
 ``runspec_linux_core.errors``).
 """
 
+from runspec_linux_core.become import (
+    BecomeError,
+    build_become,
+    check_become_error,
+    current_user,
+    escalation_supported,
+    validate_user,
+)
 from runspec_linux_core.commands import which
 from runspec_linux_core.containers import (
     container_logs,
@@ -17,9 +25,23 @@ from runspec_linux_core.containers import (
 )
 from runspec_linux_core.errors import CommandError, LinuxCoreError, ToolNotFoundError
 from runspec_linux_core.files import backup_files, find_large_files
+from runspec_linux_core.investigate import (
+    failed_units,
+    open_ports,
+    owning_package,
+    service_detail,
+)
 from runspec_linux_core.logs import journalctl, search_log, tail_log
 from runspec_linux_core.nc import nc_send
-from runspec_linux_core.network import check_port, ping_host, show_connections
+from runspec_linux_core.network import (
+    check_port,
+    dns_config,
+    ping_host,
+    route_table,
+    show_connections,
+    socket_stats,
+    trace_route,
+)
 from runspec_linux_core.packages import (
     detect_manager,
     install_package,
@@ -28,6 +50,7 @@ from runspec_linux_core.packages import (
     remove_package,
     upgrade_packages,
 )
+from runspec_linux_core.perf import cpu_info, get_sysctl, pressure, set_sysctl
 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
@@ -40,6 +63,13 @@ __all__ = [
     "LinuxCoreError",
     "ToolNotFoundError",
     "CommandError",
+    # become (privilege escalation)
+    "BecomeError",
+    "build_become",
+    "check_become_error",
+    "current_user",
+    "escalation_supported",
+    "validate_user",
     # system
     "system_info",
     "disk_usage",
@@ -57,6 +87,20 @@ __all__ = [
     "ping_host",
     "check_port",
     "show_connections",
+    "trace_route",
+    "route_table",
+    "socket_stats",
+    "dns_config",
+    # perf tuning & analysis
+    "get_sysctl",
+    "set_sysctl",
+    "cpu_info",
+    "pressure",
+    # app discovery & investigation
+    "service_detail",
+    "open_ports",
+    "owning_package",
+    "failed_units",
     # files
     "find_large_files",
     "backup_files",

runspec_linux_core-0.4.0/runspec_linux_core/become.py

@@ -0,0 +1,97 @@
+"""Privilege-escalation command builder — run a command as another OS user via
+``sudo -n -u <user>`` / ``su <user> -c``.
+
+This is the single source of truth for runspec-linux's per-invocation ``run_as``
+escalation (mechanism B): the venv runnables and the ``--run-as`` / ``--sudo``
+args on the privileged runnables all build their become command here. It is a
+sibling of ``runspec_fs_core.become`` (kept a separate copy because the ``*-core``
+packages stay dependency-free and must not cross-import); the canonical user
+regex here allows a dot (``[a-z0-9_.-]``), a superset of the fs-core form, so it
+matches ``sudoers._USER_RE`` and every name runspec-linux already accepts.
+
+Pure and stdlib-only: this *builds and validates* the become command; executing
+it (and interpreting a passwordless-sudo failure) stays with the caller — see
+``_check`` in ``venvs.py`` and ``check_become_error`` below.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+
+from runspec_linux_core.errors import CommandError
+
+# A POSIX-ish user/group name, validated before it is interpolated into a become
+# command (or a chgrp) so a crafted value can't inject extra tokens — everything
+# still goes to argv, never a shell, but this keeps the error early and clear.
+# Allows a dot, matching sudoers._USER_RE and the historical venvs._NAME_RE.
+_USER_RE = re.compile(r"^[a-z_][a-z0-9_.-]*\$?$")
+
+BECOME_METHODS = ("sudo", "su")
+
+
+class BecomeError(CommandError):
+    """An invalid run-as user, or an unsupported / unavailable become method."""
+
+
+def validate_user(name: str) -> str:
+    """Raise :class:`BecomeError` unless ``name`` is a well-formed OS user name;
+    return it unchanged on success (so it can be used inline)."""
+    if not name or not _USER_RE.match(name):
+        raise BecomeError(f"invalid run-as user: {name!r}")
+    return name
+
+
+def build_become(argv: list[str], run_as: str | None, method: str = "sudo") -> list[str]:
+    """Wrap ``argv`` so it runs as ``run_as``. Returns ``argv`` unchanged when
+    ``run_as`` is falsy (no escalation requested).
+
+    - ``sudo`` → ``sudo -n -u <user> <argv...>`` (``-n`` never prompts, so a
+      missing passwordless-sudo rule fails fast instead of hanging on a
+      TTY-less SSH/agent channel).
+    - ``su``   → ``su <user> -c '<argv...>'`` (su has no ``-n``; it only works
+      without a password when the caller is already root).
+    """
+    if not run_as:
+        return argv
+    validate_user(run_as)
+    if method not in BECOME_METHODS:
+        raise CommandError(f"invalid become-method: {method!r} (expected sudo or su)")
+    if method == "su":
+        return ["su", run_as, "-c", shlex.join(argv)]
+    return ["sudo", "-n", "-u", run_as, *argv]
+
+
+def check_become_error(what: str, stderr: str, run_as: str | None) -> None:
+    """Raise :class:`CommandError` for a failed escalated subprocess, adding a
+    passwordless-sudo hint on the classic "password/terminal required" cases.
+
+    ``what`` labels the operation; ``stderr`` is the subprocess's captured
+    stderr; ``run_as`` is the target user (``None`` when no escalation was in
+    play — then the hint is skipped). Shared by the venv helpers and the new
+    ``--run-as`` / ``--sudo`` runnables so the message is identical everywhere.
+    """
+    err = stderr.strip()
+    low = err.lower()
+    if run_as and ("password is required" in low or "a terminal is required" in low):
+        raise CommandError(f"{what}: passwordless sudo is not configured for run-as {run_as!r} ({err})")
+    raise CommandError(err or f"{what} failed")
+
+
+def escalation_supported() -> bool:
+    """True on a POSIX host where ``sudo``/``su`` escalation makes sense."""
+    return hasattr(os, "geteuid")
+
+
+def current_user() -> str:
+    """The effective OS user name — used to decide whether escalation is needed
+    (running as the user you already are is a no-op)."""
+    try:
+        import pwd
+
+        return pwd.getpwuid(os.geteuid()).pw_name
+    except (ImportError, KeyError, AttributeError):
+        import getpass
+
+        return getpass.getuser()

runspec_linux_core-0.4.0/runspec_linux_core/investigate.py

@@ -0,0 +1,217 @@
+"""Application discovery & investigation helpers — answer "where does this
+bespoke app live, what runs it, what's it listening on, and which package owns
+this file" for corporate application support.
+
+- ``service_detail`` — a systemd unit's ExecStart / working dir / user / env
+  files / active state (from ``systemctl show``).
+- ``open_ports`` — listening sockets mapped to pid → process (from ``ss -tlnp``);
+  the full pid map needs privilege, so it takes ``run_as`` / ``become_method``.
+- ``owning_package`` — which package owns a path (dpkg / rpm).
+- ``failed_units`` — systemd units in the failed state.
+
+Parsers are separated from the subprocess I/O so they unit-test without the
+real tools.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+
+from runspec_linux_core.become import build_become, check_become_error
+from runspec_linux_core.errors import CommandError, ToolNotFoundError
+
+# systemctl show properties worth surfacing for "where does this app live".
+_SERVICE_PROPS = [
+    "Id",
+    "Description",
+    "LoadState",
+    "ActiveState",
+    "SubState",
+    "UnitFileState",
+    "FragmentPath",
+    "ExecStart",
+    "WorkingDirectory",
+    "User",
+    "Group",
+    "EnvironmentFiles",
+    "MainPID",
+]
+
+
+def _parse_show(text: str) -> dict[str, str]:
+    """Parse ``systemctl show`` ``key=value`` output into a dict."""
+    props: dict[str, str] = {}
+    for line in text.splitlines():
+        if "=" in line:
+            k, v = line.split("=", 1)
+            props[k] = v
+    return props
+
+
+def _exec_start_path(exec_start: str) -> str:
+    """Pull the binary path out of a systemd ExecStart property value.
+
+    ExecStart is rendered as ``{ path=/usr/bin/foo ; argv[]=... }`` by
+    ``systemctl show``; fall back to the first token otherwise.
+    """
+    m = re.search(r"path=(\S+)", exec_start)
+    if m:
+        return m.group(1)
+    return exec_start.split(";", 1)[0].strip().split(" ", 1)[0]
+
+
+def service_detail(unit: str, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return where a systemd unit lives: ExecStart binary, working dir, user,
+    env files, unit-file path, and active state.
+
+    Some properties on protected units need privilege, so ``run_as`` /
+    ``become_method`` escalate the ``systemctl show``. Raises ToolNotFoundError if
+    systemctl is absent.
+    """
+    if not shutil.which("systemctl"):
+        raise ToolNotFoundError("systemctl not available — not a systemd system")
+
+    cmd = ["systemctl", "show", unit, "--property=" + ",".join(_SERVICE_PROPS)]
+    result = subprocess.run(build_become(cmd, run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("service detail", result.stderr, run_as)
+
+    props = _parse_show(result.stdout)
+    exec_start = props.get("ExecStart", "")
+    return {
+        "unit": props.get("Id", unit),
+        "description": props.get("Description", ""),
+        "load_state": props.get("LoadState", ""),
+        "active_state": props.get("ActiveState", ""),
+        "sub_state": props.get("SubState", ""),
+        "unit_file_state": props.get("UnitFileState", ""),
+        "fragment_path": props.get("FragmentPath", ""),
+        "exec_start": exec_start,
+        "exec_start_path": _exec_start_path(exec_start) if exec_start else "",
+        "working_directory": props.get("WorkingDirectory", ""),
+        "user": props.get("User", ""),
+        "group": props.get("Group", ""),
+        "environment_files": props.get("EnvironmentFiles", ""),
+        "main_pid": props.get("MainPID", ""),
+    }
+
+
+_PEER_WILDCARD_RE = re.compile(r"^[\d.a-fA-F:\[\]*]+:\*$")
+
+
+def _parse_ss_listening(text: str) -> list[dict]:
+    """Parse ``ss -tlnp`` / ``-ulnp`` / ``-tulnp`` output into listening-socket
+    rows with port → pid/process.
+
+    Column layout shifts with the flags (``-tu`` prepends a Netid column that
+    ``-t`` alone omits), so the local address is anchored on the wildcard peer
+    field (``*:*`` / ``0.0.0.0:*`` / ``[::]:*``) rather than a fixed index.
+    """
+    rows: list[dict] = []
+    lines = text.strip().splitlines()
+    for line in lines[1:] if lines else []:  # skip header
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+
+        peer_idx = next((i for i, p in enumerate(parts) if _PEER_WILDCARD_RE.match(p)), None)
+        if peer_idx is None or peer_idx == 0:
+            continue
+        local = parts[peer_idx - 1]
+        port = local.rsplit(":", 1)[-1]
+        # A leading Netid column (tcp/udp) is present with -tu but not -t alone.
+        proto = parts[0] if parts[0] in ("tcp", "udp", "tcp6", "udp6") else ""
+
+        procs: list[dict] = []
+        m = re.search(r"users:\(\((.*)\)\)", line)
+        if m:
+            for pm in re.finditer(r'"([^"]+)",pid=(\d+)', m.group(1)):
+                procs.append({"process": pm.group(1), "pid": int(pm.group(2))})
+        rows.append({"proto": proto, "local": local, "port": port, "processes": procs})
+    return rows
+
+
+def open_ports(proto: str = "tcp", *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return listening sockets mapped to the owning process (port → pid → name).
+
+    The full pid/process map needs privilege (``ss`` only shows other users'
+    processes as root), so ``run_as`` / ``become_method`` escalate the probe.
+    ``proto`` is ``tcp`` / ``udp`` / ``both``. Raises ToolNotFoundError if ``ss``
+    is absent.
+    """
+    if not shutil.which("ss"):
+        raise ToolNotFoundError("ss not available (iproute2)")
+
+    flags = {"tcp": "-tlnp", "udp": "-ulnp", "both": "-tulnp"}.get(proto)
+    if flags is None:
+        raise ValueError(f"invalid proto: {proto!r} (expected tcp, udp, or both)")
+
+    result = subprocess.run(build_become(["ss", flags], run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("open ports", result.stderr, run_as)
+
+    rows = _parse_ss_listening(result.stdout)
+    out = {"proto": proto, "count": len(rows), "listeners": rows}
+    if run_as:
+        out["run_as"] = run_as
+    return out
+
+
+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;
+    returns ``{owned: False}`` when the file belongs to no package.
+    """
+    if shutil.which("dpkg"):
+        result = subprocess.run(["dpkg", "-S", path], capture_output=True, text=True)
+        if result.returncode == 0 and ":" in result.stdout:
+            pkg = result.stdout.split(":", 1)[0].strip()
+            return {"path": path, "owned": True, "package": pkg, "manager": "dpkg"}
+        return {"path": path, "owned": False, "manager": "dpkg"}
+    if shutil.which("rpm"):
+        result = subprocess.run(["rpm", "-qf", path], capture_output=True, text=True)
+        if result.returncode == 0 and result.stdout.strip():
+            return {"path": path, "owned": True, "package": result.stdout.strip(), "manager": "rpm"}
+        return {"path": path, "owned": False, "manager": "rpm"}
+    raise ToolNotFoundError("neither dpkg nor rpm found — cannot resolve package ownership")
+
+
+def _parse_failed_units(text: str) -> list[dict]:
+    """Parse ``systemctl --failed --no-legend`` output into unit rows."""
+    rows: list[dict] = []
+    for line in text.strip().splitlines():
+        # A leading bullet ("● ") may appear; strip non-unit prefix tokens.
+        parts = line.replace("●", " ").split(None, 4)
+        if len(parts) < 4:
+            continue
+        rows.append(
+            {
+                "unit": parts[0],
+                "load": parts[1],
+                "active": parts[2],
+                "sub": parts[3],
+                "description": parts[4] if len(parts) > 4 else "",
+            }
+        )
+    return rows
+
+
+def failed_units() -> dict:
+    """Return systemd units currently in the failed state (``systemctl --failed``).
+
+    Raises ToolNotFoundError if systemctl is absent, or CommandError on failure.
+    """
+    if not shutil.which("systemctl"):
+        raise ToolNotFoundError("systemctl not available — not a systemd system")
+
+    result = subprocess.run(
+        ["systemctl", "--failed", "--type=service", "--no-legend", "--no-pager", "--plain"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise CommandError(result.stderr.strip() or "systemctl --failed failed")
+    rows = _parse_failed_units(result.stdout)
+    return {"count": len(rows), "units": rows}

runspec_linux_core-0.4.0/runspec_linux_core/logs.py

@@ -0,0 +1,99 @@
+"""Log helpers: tail a file, search a file, read journald units.
+
+Corporate application logs are often root-owned (or owned by a service
+account), so each helper takes an optional ``run_as`` user (with a
+``become_method``). When set, the read is performed by a subprocess escalated
+via ``sudo -n -u`` / ``su`` (:func:`runspec_linux_core.become.build_become`) — a
+faithful escalation of the same read, bounded by that user's OS permissions.
+With no ``run_as`` the read stays in-process (unchanged).
+"""
+
+import re
+import shutil
+import subprocess
+
+from runspec_linux_core.become import build_become, check_become_error
+from runspec_linux_core.errors import ToolNotFoundError
+
+
+def tail_log(file_path: str, lines: int = 50, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return the last ``lines`` lines of a text file.
+
+    With ``run_as`` set the read is escalated via ``tail -n`` under sudo/su (so a
+    root-owned log is readable); otherwise it reads in-process. Propagates OSError
+    if an in-process read fails, or CommandError if the escalated read fails.
+    """
+    if run_as:
+        argv = build_become(["tail", "-n", str(lines), file_path], run_as, become_method)
+        result = subprocess.run(argv, capture_output=True, text=True)
+        if result.returncode != 0:
+            check_become_error("tail log", result.stderr, run_as)
+        tail = result.stdout.splitlines()
+        return {"file": file_path, "lines": tail, "count": len(tail), "run_as": run_as}
+
+    with open(file_path, errors="replace") as f:
+        all_lines = f.readlines()
+    tail = [line.rstrip("\n") for line in all_lines[-lines:]]
+    return {"file": file_path, "lines": tail, "count": len(tail)}
+
+
+def search_log(file_path: str, pattern: str, limit: int = 100, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return up to ``limit`` (most recent) lines of a file matching ``pattern``.
+
+    The match is always Python ``re`` (case-insensitive). With ``run_as`` set the
+    file is read via ``cat`` under sudo/su (so a root-owned log is searchable) and
+    the same regex is applied; otherwise it streams the file in-process. Propagates
+    OSError / re.error in-process, or CommandError if the escalated read fails.
+    """
+    regex = re.compile(pattern, re.IGNORECASE)
+    matches: list[str] = []
+
+    if run_as:
+        argv = build_become(["cat", file_path], run_as, become_method)
+        result = subprocess.run(argv, capture_output=True, text=True)
+        if result.returncode != 0:
+            check_become_error("read log", result.stderr, run_as)
+        for line in result.stdout.splitlines():
+            if regex.search(line):
+                matches.append(line)
+    else:
+        with open(file_path, errors="replace") as f:
+            for line in f:
+                if regex.search(line):
+                    matches.append(line.rstrip("\n"))
+
+    trimmed = matches[-limit:] if len(matches) > limit else matches
+    result_dict = {
+        "file": file_path,
+        "pattern": pattern,
+        "matches": trimmed,
+        "count": len(trimmed),
+        "total_matches": len(matches),
+    }
+    if run_as:
+        result_dict["run_as"] = run_as
+    return result_dict
+
+
+def journalctl(unit: str, lines: int = 50, since: str | None = None, *, run_as: str | None = None, become_method: str = "sudo") -> dict:
+    """Return recent journald log lines for a systemd unit.
+
+    With ``run_as`` set the query is escalated via sudo/su (so protected units
+    outside the ``systemd-journal`` group are readable). Raises ToolNotFoundError
+    if journalctl is not present, or CommandError if the query exits non-zero.
+    """
+    if not shutil.which("journalctl"):
+        raise ToolNotFoundError("journalctl not available — not a systemd system")
+
+    cmd = ["journalctl", f"-u{unit}", f"-n{lines}", "--no-pager", "--output=short"]
+    if since:
+        cmd += [f"--since={since}"]
+
+    result = subprocess.run(build_become(cmd, run_as, become_method), capture_output=True, text=True)
+    if result.returncode != 0:
+        check_become_error("journalctl", result.stderr, run_as)
+    output_lines = result.stdout.strip().splitlines()
+    out = {"unit": unit, "lines": output_lines, "count": len(output_lines)}
+    if run_as:
+        out["run_as"] = run_as
+    return out