runspec-linux 0.18.0__tar.gz → 0.19.0__tar.gz

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # runspec-linux Changelog
 
+## [0.19.0] — 2026-09-30
+
+**No root in runspec-linux.** Everything here now runs as an unprivileged
+account: you, or the service account that owns a shared venv (runspec >= 0.68.0
+runs a shared venv's tools as its owner). The tools that need root moved to the
+new **`runspec-linux-root`** package, for a root-owned admin venv.
+
+### Removed (moved to `runspec-linux-root`)
+
+- `list-upgrades`, `upgrade-packages`, `install-package`, `remove-package`,
+  `autoremove-packages`, `set-sysctl`, `reboot-host`, `enable-passwordless-sudo`.
+  Their helpers stay in `runspec-linux-core`. The `runspec_linux` re-exports of
+  `install_package`, `list_upgrades`, `reboot_host`, `remove_package`,
+  `upgrade_packages` and `enable_passwordless_sudo` are gone: import them from
+  `runspec_linux_core`.
+- **`--sudo`** ("run as root") on `restart-service`, `tail-log`, `search-log`,
+  `journalctl`, `list-containers`, `container-logs`, `restart-container`,
+  `service-detail` and `open-ports`.
+
+### Changed
+
+- **`--run-as root` is refused** on every tool that takes `--run-as` (the ones
+  above, the venv tools, `filesystem` and `cron`). It prints a JSON error naming
+  `runspec-linux-root` and exits 2. `--run-as` still selects any unprivileged
+  account.
+- **`--run-as` naming the account you already are does nothing** (from
+  runspec-linux-core 0.13.0). A service account running its own venv's tools with
+  `--run-as <itself>` used to need a sudoers rule letting it sudo to itself.
+
+### Upgrading
+
+Install `runspec-linux-root` into a separate root-owned venv (see its README).
+If an existing venv has both packages, upgrade `runspec-linux` first: pip
+removes the old copies of the moved scripts when it upgrades it.
+
 ## [0.18.0] — 2026-09-29
 
 ### Added

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runspec-linux
-Version: 0.18.0
+Version: 0.19.0
 Summary: Linux system admin runnables for runspec
 Project-URL: Documentation, https://runspec.app/
 Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux
@@ -9,7 +9,7 @@ Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
 Keywords: linux,ops,runnable,runspec,ssh,sysadmin,venv
 Requires-Python: >=3.10
 Requires-Dist: runspec-fs-core>=0.5.0
-Requires-Dist: runspec-linux-core>=0.12.0
+Requires-Dist: runspec-linux-core>=0.13.0
 Requires-Dist: runspec-webops-core>=0.3.0
 Requires-Dist: runspec>=0.50.1
 Provides-Extra: dev
@@ -27,10 +27,15 @@ the runnables are discoverable by `runspec local`, `runspec serve` (MCP), and
 runspec-console.
 
 All runnables emit JSON on stdout. Read-only runnables are `autonomy =
-"autonomous"`; state-changing ones are `autonomy = "confirm"`. The privileged
-runnables declare `run_as = "root"`, so runspec-console escalates them via
-`sudo` — run `enable-passwordless-sudo` once to install a `visudo`-validated
-`/etc/sudoers.d` drop-in so they run without a password prompt.
+"autonomous"`; state-changing ones are `autonomy = "confirm"`.
+
+**Nothing here runs as root.** A tool runs as whoever owns its venv (runspec
+>= 0.68.0): you in a personal venv, or the service account in a shared one.
+`--run-as` picks another unprivileged account and refuses `root`. The tools that
+need root (package upgrades/installs, `reboot-host`, `set-sysctl`,
+`enable-passwordless-sudo`) are in
+[`runspec-linux-root`](https://pypi.org/project/runspec-linux-root/), for a
+root-owned admin venv.
 
 ## Install
 
@@ -47,13 +52,11 @@ pip install runspec-linux
 | Services | `list-services`, `check-service`, `restart-service`, `service-detail`, `failed-units` |
 | Logs | `tail-log`, `search-log`, `journalctl` |
 | Network | `network-interfaces`, `ping-host`, `check-port`, `show-connections`, `trace-route`, `route-table`, `socket-stats`, `dns-config`, `open-ports` |
-| Kernel params | `get-sysctl`, `set-sysctl` |
+| Kernel params | `get-sysctl` |
 | Files | `find-large-files`, `backup-files`, `owning-package` |
 | Sessions | `last-logins`, `who` |
 | Containers | `list-containers`, `container-logs`, `restart-container` |
-| Packages | `list-packages`, `list-upgrades`, `upgrade-packages`, `install-package`, `remove-package`, `autoremove-packages`, `list-autoremovable` |
-| Power | `reboot-host` |
-| Sudo bootstrap | `enable-passwordless-sudo` |
+| Packages (read-only) | `list-packages`, `list-autoremovable` |
 | Python venvs | `create-venv`, `install-into-venv`, `configure-pip` |
 | TCP | `nc-command` |
 | Commands | `which` |
@@ -61,13 +64,13 @@ pip install runspec-linux
 | Filesystem | `filesystem` (multi-verb, backed by `runspec-fs-core`) |
 | Web / TLS / API | `cert-check`, `cert-chain`, `tls-info`, `http-check`, `http-headers`, `redirect-trace`, `dns-lookup`, `api-spec` |
 
-The package-management runnables auto-detect apt / dnf / yum / zypper / pacman.
+The package runnables auto-detect apt / dnf / yum / zypper / pacman.
 The web/TLS/API probes are pure HTTP (shared with `runspec-windows` via
 `runspec-webops-core`) and run anywhere.
 
 ```
 system-info
-list-upgrades
+list-packages --filter nginx
 check-port --host db-01 --port 5432
 cert-check --url https://internal.example.com
 ```

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/README.md

@@ -7,10 +7,15 @@ the runnables are discoverable by `runspec local`, `runspec serve` (MCP), and
 runspec-console.
 
 All runnables emit JSON on stdout. Read-only runnables are `autonomy =
-"autonomous"`; state-changing ones are `autonomy = "confirm"`. The privileged
-runnables declare `run_as = "root"`, so runspec-console escalates them via
-`sudo` — run `enable-passwordless-sudo` once to install a `visudo`-validated
-`/etc/sudoers.d` drop-in so they run without a password prompt.
+"autonomous"`; state-changing ones are `autonomy = "confirm"`.
+
+**Nothing here runs as root.** A tool runs as whoever owns its venv (runspec
+>= 0.68.0): you in a personal venv, or the service account in a shared one.
+`--run-as` picks another unprivileged account and refuses `root`. The tools that
+need root (package upgrades/installs, `reboot-host`, `set-sysctl`,
+`enable-passwordless-sudo`) are in
+[`runspec-linux-root`](https://pypi.org/project/runspec-linux-root/), for a
+root-owned admin venv.
 
 ## Install
 
@@ -27,13 +32,11 @@ pip install runspec-linux
 | Services | `list-services`, `check-service`, `restart-service`, `service-detail`, `failed-units` |
 | Logs | `tail-log`, `search-log`, `journalctl` |
 | Network | `network-interfaces`, `ping-host`, `check-port`, `show-connections`, `trace-route`, `route-table`, `socket-stats`, `dns-config`, `open-ports` |
-| Kernel params | `get-sysctl`, `set-sysctl` |
+| Kernel params | `get-sysctl` |
 | Files | `find-large-files`, `backup-files`, `owning-package` |
 | Sessions | `last-logins`, `who` |
 | Containers | `list-containers`, `container-logs`, `restart-container` |
-| Packages | `list-packages`, `list-upgrades`, `upgrade-packages`, `install-package`, `remove-package`, `autoremove-packages`, `list-autoremovable` |
-| Power | `reboot-host` |
-| Sudo bootstrap | `enable-passwordless-sudo` |
+| Packages (read-only) | `list-packages`, `list-autoremovable` |
 | Python venvs | `create-venv`, `install-into-venv`, `configure-pip` |
 | TCP | `nc-command` |
 | Commands | `which` |
@@ -41,13 +44,13 @@ pip install runspec-linux
 | Filesystem | `filesystem` (multi-verb, backed by `runspec-fs-core`) |
 | Web / TLS / API | `cert-check`, `cert-chain`, `tls-info`, `http-check`, `http-headers`, `redirect-trace`, `dns-lookup`, `api-spec` |
 
-The package-management runnables auto-detect apt / dnf / yum / zypper / pacman.
+The package runnables auto-detect apt / dnf / yum / zypper / pacman.
 The web/TLS/API probes are pure HTTP (shared with `runspec-windows` via
 `runspec-webops-core`) and run anywhere.
 
 ```
 system-info
-list-upgrades
+list-packages --filter nginx
 check-port --host db-01 --port 5432
 cert-check --url https://internal.example.com
 ```

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux"
-version = "0.18.0"
+version = "0.19.0"
 requires-python = ">=3.10"
 description = "Linux system admin runnables for runspec"
 readme = "README.md"
 keywords = ["runspec", "runnable", "linux", "sysadmin", "ops", "ssh", "venv"]
 dependencies = [
     "runspec>=0.50.1",
-    "runspec-linux-core>=0.12.0",
+    "runspec-linux-core>=0.13.0",
     "runspec-webops-core>=0.3.0",
     "runspec-fs-core>=0.5.0",
 ]
@@ -43,7 +43,6 @@ socket-stats      = "runspec_linux.network:main_socket_stats"
 dns-config        = "runspec_linux.network:main_dns_config"
 network-interfaces = "runspec_linux.network:main_network_interfaces"
 get-sysctl        = "runspec_linux.perf:main_get_sysctl"
-set-sysctl        = "runspec_linux.perf:main_set_sysctl"
 cpu-info          = "runspec_linux.perf:main_cpu_info"
 pressure          = "runspec_linux.perf:main_pressure"
 service-detail    = "runspec_linux.investigate:main_service_detail"
@@ -58,14 +57,7 @@ list-containers   = "runspec_linux.containers:main_list_containers"
 container-logs    = "runspec_linux.containers:main_container_logs"
 restart-container = "runspec_linux.containers:main_restart_container"
 list-packages     = "runspec_linux.packages:main_list_packages"
-list-upgrades     = "runspec_linux.packages:main_list_upgrades"
-upgrade-packages  = "runspec_linux.packages:main_upgrade_packages"
-install-package   = "runspec_linux.packages:main_install_package"
-remove-package    = "runspec_linux.packages:main_remove_package"
-autoremove-packages = "runspec_linux.packages:main_autoremove_packages"
 list-autoremovable  = "runspec_linux.packages:main_list_autoremovable"
-reboot-host       = "runspec_linux.power:main_reboot_host"
-enable-passwordless-sudo = "runspec_linux.sudoers:main_enable_passwordless_sudo"
 create-venv       = "runspec_linux.venvs:main_create_venv"
 install-into-venv = "runspec_linux.venvs:main_install_into_venv"
 configure-pip     = "runspec_linux.venvs:main_configure_pip"

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/__init__.py

@@ -4,7 +4,8 @@ The pure logic lives in the dependency-free ``runspec-linux-core`` package; the
 modules here wrap each helper in a runspec runnable. The helper functions are
 re-exported for convenience and back-compat (e.g. ``from runspec_linux import
 nc_send``). To import the helpers *without* surfacing any runnables in a venv,
-depend on ``runspec-linux-core`` directly instead.
+depend on ``runspec-linux-core`` directly instead. Tools that need root live in
+``runspec-linux-root``; their helpers are in ``runspec-linux-core``.
 """
 
 from runspec_linux_core import (
@@ -19,10 +20,8 @@ from runspec_linux_core import (
     create_venv,
     detect_manager,
     disk_usage,
-    enable_passwordless_sudo,
     find_large_files,
     install_into_venv,
-    install_package,
     journalctl,
     last_logins,
     list_containers,
@@ -30,19 +29,15 @@ from runspec_linux_core import (
     list_packages,
     list_processes,
     list_services,
-    list_upgrades,
     nc_send,
     ping_host,
-    reboot_host,
     remove_cron,
-    remove_package,
     restart_container,
     restart_service,
     search_log,
     show_connections,
     system_info,
     tail_log,
-    upgrade_packages,
     which,
     who,
 )
@@ -59,10 +54,8 @@ __all__ = [
     "create_venv",
     "detect_manager",
     "disk_usage",
-    "enable_passwordless_sudo",
     "find_large_files",
     "install_into_venv",
-    "install_package",
     "journalctl",
     "last_logins",
     "list_containers",
@@ -70,19 +63,15 @@ __all__ = [
     "list_packages",
     "list_processes",
     "list_services",
-    "list_upgrades",
     "nc_send",
     "ping_host",
-    "reboot_host",
     "remove_cron",
-    "remove_package",
     "restart_container",
     "restart_service",
     "search_log",
     "show_connections",
     "system_info",
     "tail_log",
-    "upgrade_packages",
     "which",
     "who",
 ]

runspec_linux-0.19.0/runspec_linux/_escalation.py

@@ -0,0 +1,42 @@
+"""Shared wrapper helper for the ``--run-as`` / ``--become-method`` escalation args.
+
+runspec-linux never escalates to root: tools that need root live in the separate
+``runspec-linux-root`` package, installed into a root-owned venv. ``--run-as``
+picks an unprivileged account (typically the service account that owns a shared
+venv); a root target is refused before anything runs.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+ROOT_REFUSAL = "runspec-linux does not run anything as root — root tools live in runspec-linux-root"
+
+
+def is_root(name: str) -> bool:
+    """True when ``name`` names uid 0 (``root``, ``0`` or any alias)."""
+    if name in ("root", "0"):
+        return True
+    try:
+        import pwd
+
+        return pwd.getpwnam(name).pw_uid == 0
+    except (ImportError, KeyError):
+        return False
+
+
+def refuse_root(run_as: str | None) -> None:
+    """Print a JSON error and exit 2 when ``run_as`` targets root."""
+    if run_as and is_root(run_as):
+        print(json.dumps({"error": f"--run-as {run_as}: {ROOT_REFUSAL}"}))
+        sys.exit(2)
+
+
+def resolve_escalation(spec: Any) -> tuple[str | None, str]:
+    """Return ``(run_as, become_method)`` from a spec carrying the escalation args
+    (``None`` = no escalation, runs as the caller). Exits on a root target."""
+    run_as = spec.run_as.value or None
+    refuse_root(run_as)
+    return run_as, spec.become_method.value

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/cron.py

@@ -23,6 +23,8 @@ import runspec as rs
 from runspec_linux_core.cron import add_cron, clear_cron, list_cron, remove_cron
 from runspec_linux_core.errors import CommandError, ToolNotFoundError
 
+from runspec_linux._escalation import refuse_root
+
 
 def _emit(payload: dict[str, Any]) -> None:
     print(json.dumps(payload, default=str))
@@ -31,6 +33,7 @@ def _emit(payload: dict[str, Any]) -> None:
 def _run(spec: rs.RunSpec) -> dict[str, Any]:
     command = spec.runspec_command
     run_as = spec.run_as.value or None
+    refuse_root(run_as)
     become_method = spec.become_method.value
 
     if command == "list":

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/fs/cli.py

@@ -26,6 +26,7 @@ from typing import Any
 import runspec as rs
 from runspec_fs_core import BecomeError, FsCoreError, build_become, current_user, escalation_supported
 
+from runspec_linux._escalation import refuse_root
 from runspec_linux.fs._dispatch import run_verb
 
 
@@ -115,6 +116,7 @@ def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any])
 def main() -> None:
     spec = rs.parse("filesystem")
     run_as = spec.run_as.value
+    refuse_root(run_as or None)
     method = spec.become_method.value
     try:
         kwargs = _verb_kwargs(spec)

runspec_linux-0.19.0/runspec_linux/packages.py

@@ -0,0 +1,27 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import list_autoremovable, list_packages
+
+
+def main_list_packages() -> None:
+    spec = rs.parse("list-packages")
+    name_filter = spec.filter.value
+    limit = spec.limit.value
+    try:
+        print(json.dumps(list_packages(name_filter, limit, reason=spec.reason.value)))
+    except Exception as e:
+        # Includes ToolNotFoundError (no package manager) and CommandError.
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+
+
+def main_list_autoremovable() -> None:
+    spec = rs.parse("list-autoremovable")
+    try:
+        print(json.dumps(list_autoremovable(purge=spec.purge.value)))
+    except Exception as e:
+        # Includes CommandError (yum, failed listing) and ToolNotFoundError.
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/perf.py

@@ -4,10 +4,7 @@ import json
 import sys
 
 import runspec as rs
-from runspec_linux_core import cpu_info, get_sysctl, pressure, set_sysctl
-from runspec_linux_core.errors import CommandError
-
-from runspec_linux._escalation import resolve_escalation
+from runspec_linux_core import cpu_info, get_sysctl, pressure
 
 
 def main_get_sysctl() -> None:
@@ -20,22 +17,6 @@ def main_get_sysctl() -> None:
         sys.exit(1)
 
 
-def main_set_sysctl() -> None:
-    spec = rs.parse("set-sysctl")
-    key = spec.key.value
-    value = spec.value.value
-    persist = spec.persist.value
-    run_as, method = resolve_escalation(spec)
-    try:
-        print(json.dumps(set_sysctl(key, value, persist=persist, run_as=run_as, become_method=method)))
-    except CommandError as e:
-        print(json.dumps({"key": key, "applied": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
 def main_cpu_info() -> None:
     rs.parse("cpu-info")
     try:

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/runspec.toml

@@ -96,24 +96,15 @@ description = "Service name to restart"
 # Escalation: restarting a system service needs privilege.
 [restart-service.args.run-as]
 type        = "str"
-description = "Run as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Run as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[restart-service.args.sudo]
-type        = "flag"
-description = "Run as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [restart-service.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[restart-service.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 # ── Logs ──────────────────────────────────────────────────────────────────────
 
 [tail-log]
@@ -133,27 +124,18 @@ short       = "-n"
 description = "Number of lines to return"
 default     = 50
 
-# Escalation: read a root-owned / service-account-owned log (tail -n under sudo/su).
+# Escalation: read a service-account-owned log (tail -n under sudo/su).
 [tail-log.args.run-as]
 type        = "str"
-description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Read as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[tail-log.args.sudo]
-type        = "flag"
-description = "Read as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [tail-log.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[tail-log.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [search-log]
 serve       = ["local"]
 description = "Search a log file for lines matching a pattern"
@@ -176,27 +158,18 @@ short       = "-n"
 description = "Maximum number of matching lines to return"
 default     = 100
 
-# Escalation: search a root-owned / service-account-owned log (cat under sudo/su).
+# Escalation: search a service-account-owned log (cat under sudo/su).
 [search-log.args.run-as]
 type        = "str"
-description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Read as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[search-log.args.sudo]
-type        = "flag"
-description = "Read as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [search-log.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[search-log.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [journalctl]
 serve       = ["local"]
 description = "Fetch recent journal entries for a systemd unit (systemd-only)"
@@ -222,24 +195,15 @@ required    = false
 # Escalation: read a protected unit's journal (outside the systemd-journal group).
 [journalctl.args.run-as]
 type        = "str"
-description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Read as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[journalctl.args.sudo]
-type        = "flag"
-description = "Read as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [journalctl.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[journalctl.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 # ── Network ───────────────────────────────────────────────────────────────────
 
 [ping-host]
@@ -375,24 +339,15 @@ default     = false
 # Escalation: the Docker daemon socket is usually root/docker-group owned.
 [list-containers.args.run-as]
 type        = "str"
-description = "Run docker as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Run docker as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[list-containers.args.sudo]
-type        = "flag"
-description = "Run docker as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [list-containers.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[list-containers.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [container-logs]
 serve       = ["local"]
 description = "Fetch recent log output from a Docker container"
@@ -413,24 +368,15 @@ default     = 50
 # Escalation: the Docker daemon socket is usually root/docker-group owned.
 [container-logs.args.run-as]
 type        = "str"
-description = "Run docker as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Run docker as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[container-logs.args.sudo]
-type        = "flag"
-description = "Run docker as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [container-logs.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[container-logs.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [restart-container]
 serve       = ["local"]
 description = "Restart a Docker container"
@@ -445,24 +391,15 @@ description = "Container name or ID"
 # Escalation: the Docker daemon socket is usually root/docker-group owned.
 [restart-container.args.run-as]
 type        = "str"
-description = "Run docker as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Run docker as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[restart-container.args.sudo]
-type        = "flag"
-description = "Run docker as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [restart-container.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[restart-container.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 # ── Packages ──────────────────────────────────────────────────────────────────
 
 [list-packages]
@@ -488,54 +425,6 @@ type        = "flag"
 description = "Also say whether each package was installed by name (manual) or as a dependency (auto) — autoremove only ever removes auto packages"
 default     = false
 
-[list-upgrades]
-serve       = ["local"]
-description = "List packages with an available upgrade (refreshes the package index first)"
-autonomy    = "autonomous"
-output      = "json"
-run_as      = "root"
-
-[list-upgrades.args.no-refresh]
-type        = "flag"
-description = "Skip refreshing the package index — list from the cached index (faster)"
-default     = false
-
-[upgrade-packages]
-serve       = ["local"]
-description = "Refresh the package index and upgrade all installed packages (needs root)"
-autonomy    = "confirm"
-output      = "json"
-run_as      = "root"
-
-[install-package]
-serve       = ["local"]
-description = "Install one or more packages by name (needs root)"
-autonomy    = "confirm"
-output      = "json"
-run_as      = "root"
-
-[install-package.args.package]
-type        = "str"
-short       = "-p"
-description = "Package name to install (space-separated for several)"
-
-[remove-package]
-serve       = ["local"]
-description = "Remove one or more packages by name (needs root)"
-autonomy    = "confirm"
-output      = "json"
-run_as      = "root"
-
-[remove-package.args.package]
-type        = "str"
-short       = "-p"
-description = "Package name to remove (space-separated for several)"
-
-[remove-package.args.purge]
-type        = "flag"
-description = "Also delete the packages' configuration files (apt purge / pacman -Rn; a plain remove on dnf/yum/zypper)"
-default     = false
-
 [list-autoremovable]
 serve       = ["local"]
 description = "List the packages autoremove-packages would remove (read-only preview; not supported on yum)"
@@ -547,66 +436,6 @@ type        = "flag"
 description = "Preview a purge (apt shows config files would go too)"
 default     = false
 
-[autoremove-packages]
-serve       = ["local"]
-description = "Remove packages nothing depends on any more, e.g. old kernels (apt autoremove and equivalents; needs root)"
-autonomy    = "confirm"
-output      = "json"
-run_as      = "root"
-
-[autoremove-packages.args.purge]
-type        = "flag"
-description = "Also delete the removed packages' configuration files (apt --purge / pacman -n)"
-default     = false
-
-[autoremove-packages.args.dry-run]
-type        = "flag"
-description = "Only list what would be removed; remove nothing (not supported on yum). list-autoremovable does the same without needing approval"
-default     = false
-
-# ── Power ─────────────────────────────────────────────────────────────────────
-
-[reboot-host]
-serve       = ["local"]
-description = "Reboot the host, optionally after a delay in minutes (needs root)"
-autonomy    = "confirm"
-output      = "json"
-run_as      = "root"
-
-[reboot-host.args.delay-minutes]
-type        = "int"
-short       = "-d"
-description = "Minutes to wait before rebooting (0 = immediately)"
-default     = 0
-
-# ── Privilege bootstrap ───────────────────────────────────────────────────────
-
-# One-time setup so the run_as="root" runnables above need no password. Itself
-# escalates with the supplied password via `sudo -S` (read from stdin, never
-# argv), so it must NOT declare run_as. Validated with visudo before + after
-# install and rolled back on failure.
-[enable-passwordless-sudo]
-serve       = ["local"]
-description = "Install a validated /etc/sudoers.d drop-in so run_as='root' runnables need no password (one-time bootstrap)"
-autonomy    = "confirm"
-output      = "json"
-
-[enable-passwordless-sudo.args.password]
-type        = "password"
-description = "Your sudo password — sent over the secret channel and piped to 'sudo -S'; never appears in argv, ps, or logs"
-
-[enable-passwordless-sudo.args.user]
-type        = "str"
-short       = "-u"
-description = "User to grant passwordless sudo (defaults to the current login user)"
-required    = false
-
-[enable-passwordless-sudo.args.scope]
-type        = "choice"
-options     = ["scoped", "all"]
-default     = "scoped"
-description = "scoped = NOPASSWD only for the runspec venv runnables (manual/CLI runs); all = NOPASSWD: ALL (also covers agent-driven runs)"
-
 # ── TCP interfaces (nc-command) ────────────────────────────────────────────────
 
 [nc-command]
@@ -1237,47 +1066,6 @@ short       = "-p"
 description = "Only return keys containing this substring (e.g. 'net.core')"
 required    = false
 
-[set-sysctl]
-serve       = ["local"]
-description = "Set a kernel parameter (sysctl -w), optionally persisting it under /etc/sysctl.d"
-autonomy    = "confirm"
-output      = "json"
-
-[set-sysctl.args.key]
-type        = "str"
-short       = "-k"
-description = "Dotted sysctl key (e.g. net.core.somaxconn)"
-
-[set-sysctl.args.value]
-type        = "str"
-description = "New value to set"
-
-[set-sysctl.args.persist]
-type        = "flag"
-description = "Also append the setting to /etc/sysctl.d/99-runspec.conf so it survives a reboot"
-default     = false
-
-# Escalation: writing a kernel parameter is privileged.
-[set-sysctl.args.run-as]
-type        = "str"
-description = "Apply as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
-required    = false
-
-[set-sysctl.args.sudo]
-type        = "flag"
-description = "Apply as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
-[set-sysctl.args.become-method]
-type        = "choice"
-options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
-default     = "sudo"
-
-[set-sysctl.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [cpu-info]
 serve       = ["local"]
 description = "Report CPU model, core count, and per-CPU scaling governor and frequency"
@@ -1306,24 +1094,15 @@ description = "Systemd unit name (e.g. nginx or nginx.service)"
 # Escalation: some properties on protected units need privilege.
 [service-detail.args.run-as]
 type        = "str"
-description = "Read as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Read as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[service-detail.args.sudo]
-type        = "flag"
-description = "Read as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [service-detail.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[service-detail.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [open-ports]
 serve       = ["local"]
 description = "List listening sockets mapped to the owning process (port to pid to process name)"
@@ -1339,24 +1118,15 @@ default     = "tcp"
 # Escalation: the full pid/process map needs privilege (ss shows other users' processes only as root).
 [open-ports.args.run-as]
 type        = "str"
-description = "Probe as this specific OS user (via sudo -n -u / su). Mutually exclusive with --sudo."
+description = "Probe as this specific OS user (via sudo -n -u / su). Never root — root tools live in runspec-linux-root."
 required    = false
 
-[open-ports.args.sudo]
-type        = "flag"
-description = "Probe as root (via sudo). Mutually exclusive with --run-as."
-default     = false
-
 [open-ports.args.become-method]
 type        = "choice"
 options     = ["sudo", "su"]
-description = "How to escalate for --run-as/--sudo: sudo (passwordless, -n) or su."
+description = "How to escalate for --run-as: sudo (passwordless, -n) or su."
 default     = "sudo"
 
-[open-ports.groups.escalation]
-exclusive   = true
-args        = ["run-as", "sudo"]
-
 [owning-package]
 serve       = ["local"]
 description = "Report which installed package owns a file path (dpkg / rpm)"

{runspec_linux-0.18.0 → runspec_linux-0.19.0}/runspec_linux/venvs.py

@@ -5,9 +5,12 @@ import runspec as rs
 from runspec_linux_core import configure_pip, create_venv, install_into_venv, share_venv_logs
 from runspec_linux_core.errors import CommandError
 
+from runspec_linux._escalation import refuse_root
+
 
 def main_create_venv() -> None:
     spec = rs.parse("create-venv")
+    refuse_root(spec.run_as.value or None)
     try:
         result = create_venv(
             str(spec.python.value),
@@ -33,6 +36,7 @@ def main_create_venv() -> None:
 
 def main_install_into_venv() -> None:
     spec = rs.parse("install-into-venv")
+    refuse_root(spec.run_as.value or None)
     try:
         result = install_into_venv(
             str(spec.venv.value),
@@ -57,6 +61,7 @@ def main_install_into_venv() -> None:
 
 def main_share_venv_logs() -> None:
     spec = rs.parse("share-venv-logs")
+    refuse_root(spec.run_as.value or None)
     try:
         result = share_venv_logs(
             str(spec.venv.value),
@@ -77,6 +82,7 @@ def main_share_venv_logs() -> None:
 
 def main_configure_pip() -> None:
     spec = rs.parse("configure-pip")
+    refuse_root(spec.run_as.value or None)
     try:
         result = configure_pip(
             spec.index_url.value,

runspec_linux-0.19.0/tests/test_escalation.py

@@ -0,0 +1,56 @@
+"""The wrapper-side escalation resolver: --run-as / --become-method →
+(run_as, become_method), refusing any root target.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from runspec_linux._escalation import is_root, refuse_root, resolve_escalation
+
+
+def _spec(run_as: str, method: str = "sudo") -> SimpleNamespace:
+    # A parsed spec exposes each arg as an object with a .value.
+    return SimpleNamespace(run_as=SimpleNamespace(value=run_as), become_method=SimpleNamespace(value=method))
+
+
+def test_run_as_user() -> None:
+    assert resolve_escalation(_spec("deploy")) == ("deploy", "sudo")
+
+
+def test_empty_is_none() -> None:
+    assert resolve_escalation(_spec("")) == (None, "sudo")
+
+
+def test_become_method_passthrough() -> None:
+    assert resolve_escalation(_spec("svc", method="su")) == ("svc", "su")
+
+
+@pytest.mark.parametrize("target", ["root", "0"])
+def test_root_is_refused(target: str, capsys: pytest.CaptureFixture[str]) -> None:
+    with pytest.raises(SystemExit) as exc:
+        resolve_escalation(_spec(target))
+    assert exc.value.code == 2
+    assert "runspec-linux-root" in json.loads(capsys.readouterr().out)["error"]
+
+
+def test_is_root() -> None:
+    assert is_root("root") and is_root("0")
+    assert not is_root("svc-no-such-user")
+    refuse_root(None)
+    refuse_root("svc")
+
+
+def test_no_root_tools_left() -> None:
+    from importlib.resources import files
+
+    tomllib = pytest.importorskip("tomllib")
+    spec = tomllib.loads((files("runspec_linux") / "runspec.toml").read_text())
+    for name, body in spec.items():
+        if name == "config":
+            continue
+        assert body.get("run_as") != "root", name
+        assert "sudo" not in (body.get("args") or {}), name

runspec_linux-0.18.0/runspec_linux/_escalation.py

@@ -1,20 +0,0 @@
-"""Shared wrapper helper for the ``--run-as`` / ``--sudo`` / ``--become-method``
-escalation args.
-
-The privileged runnables declare a mutually-exclusive ``escalation`` group with
-``--run-as <user>`` and ``--sudo`` (a flag = "run as root"), plus
-``--become-method sudo|su``. The group guarantees at most one of run-as/sudo is
-set, so this resolves them to the ``(run_as, become_method)`` the core helpers
-take: ``--sudo`` → ``run_as="root"``, ``--run-as x`` → ``run_as="x"``, neither →
-``run_as=None`` (no escalation, runs as the login user).
-"""
-
-from __future__ import annotations
-
-import runspec as rs
-
-
-def resolve_escalation(spec: rs.RunSpec) -> tuple[str | None, str]:
-    """Return ``(run_as, become_method)`` from a spec carrying the escalation args."""
-    run_as = "root" if spec.sudo.value else (spec.run_as.value or None)
-    return run_as, spec.become_method.value

runspec_linux-0.18.0/runspec_linux/packages.py

@@ -1,99 +0,0 @@
-import json
-import sys
-
-import runspec as rs
-from runspec_linux_core import (
-    autoremove_packages,
-    install_package,
-    list_autoremovable,
-    list_packages,
-    list_upgrades,
-    remove_package,
-    upgrade_packages,
-)
-from runspec_linux_core.errors import CommandError
-
-
-def main_list_packages() -> None:
-    spec = rs.parse("list-packages")
-    name_filter = spec.filter.value
-    limit = spec.limit.value
-    try:
-        print(json.dumps(list_packages(name_filter, limit, reason=spec.reason.value)))
-    except Exception as e:
-        # Includes ToolNotFoundError (no package manager) and CommandError.
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_list_upgrades() -> None:
-    spec = rs.parse("list-upgrades")
-    try:
-        print(json.dumps(list_upgrades(refresh=not spec.no_refresh.value)))
-    except Exception as e:
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_upgrade_packages() -> None:
-    rs.parse("upgrade-packages")
-    try:
-        print(json.dumps(upgrade_packages()))
-    except CommandError as e:
-        print(json.dumps({"upgraded": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ToolNotFoundError (no package manager).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_install_package() -> None:
-    spec = rs.parse("install-package")
-    package = spec.package.value
-    try:
-        print(json.dumps(install_package(package)))
-    except CommandError as e:
-        print(json.dumps({"package": package, "installed": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ValueError (bad name) and ToolNotFoundError (no package manager).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_remove_package() -> None:
-    spec = rs.parse("remove-package")
-    package = spec.package.value
-    try:
-        print(json.dumps(remove_package(package, purge=spec.purge.value)))
-    except CommandError as e:
-        print(json.dumps({"package": package, "removed": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ValueError (bad name) and ToolNotFoundError (no package manager).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_list_autoremovable() -> None:
-    spec = rs.parse("list-autoremovable")
-    try:
-        print(json.dumps(list_autoremovable(purge=spec.purge.value)))
-    except Exception as e:
-        # Includes CommandError (yum, failed listing) and ToolNotFoundError.
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)
-
-
-def main_autoremove_packages() -> None:
-    spec = rs.parse("autoremove-packages")
-    try:
-        print(json.dumps(autoremove_packages(purge=spec.purge.value, dry_run=spec.dry_run.value)))
-    except CommandError as e:
-        print(json.dumps({"removed": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ToolNotFoundError (no package manager).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)

runspec_linux-0.18.0/runspec_linux/power.py

@@ -1,20 +0,0 @@
-import json
-import sys
-
-import runspec as rs
-from runspec_linux_core import reboot_host
-from runspec_linux_core.errors import CommandError
-
-
-def main_reboot_host() -> None:
-    spec = rs.parse("reboot-host")
-    delay_minutes = spec.delay_minutes.value
-    try:
-        print(json.dumps(reboot_host(delay_minutes)))
-    except CommandError as e:
-        print(json.dumps({"scheduled": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ToolNotFoundError (no shutdown/systemctl).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)

runspec_linux-0.18.0/runspec_linux/sudoers.py

@@ -1,23 +0,0 @@
-import json
-import sys
-
-import runspec as rs
-from runspec_linux_core import enable_passwordless_sudo
-from runspec_linux_core.errors import CommandError
-
-
-def main_enable_passwordless_sudo() -> None:
-    spec = rs.parse("enable-passwordless-sudo")
-    password = spec.password.value
-    user = spec.user.value
-    scope = spec.scope.value
-    try:
-        print(json.dumps(enable_passwordless_sudo(password, user, scope)))
-    except CommandError as e:
-        # Auth failure / sudoers validation failure (rolled back).
-        print(json.dumps({"installed": False, "error": str(e)}))
-        sys.exit(1)
-    except Exception as e:
-        # Includes ValueError (bad scope/user) and ToolNotFoundError (no sudo/visudo).
-        print(json.dumps({"error": str(e)}))
-        sys.exit(1)

runspec_linux-0.18.0/tests/test_escalation.py

@@ -1,34 +0,0 @@
-"""The wrapper-side escalation resolver: --sudo / --run-as / --become-method →
-(run_as, become_method).
-"""
-
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-from runspec_linux._escalation import resolve_escalation
-
-
-def _spec(sudo: bool, run_as: str, method: str = "sudo") -> SimpleNamespace:
-    # A parsed spec exposes each arg as an object with a .value.
-    return SimpleNamespace(
-        sudo=SimpleNamespace(value=sudo),
-        run_as=SimpleNamespace(value=run_as),
-        become_method=SimpleNamespace(value=method),
-    )
-
-
-def test_sudo_maps_to_root() -> None:
-    assert resolve_escalation(_spec(sudo=True, run_as="")) == ("root", "sudo")
-
-
-def test_run_as_user() -> None:
-    assert resolve_escalation(_spec(sudo=False, run_as="deploy")) == ("deploy", "sudo")
-
-
-def test_neither_is_none() -> None:
-    assert resolve_escalation(_spec(sudo=False, run_as="")) == (None, "sudo")
-
-
-def test_become_method_passthrough() -> None:
-    assert resolve_escalation(_spec(sudo=False, run_as="svc", method="su")) == ("svc", "su")