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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/.gitignore +5 -0
  2. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/CHANGELOG.md +41 -0
  3. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/PKG-INFO +12 -16
  4. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/README.md +7 -11
  5. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/pyproject.toml +5 -9
  6. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/__init__.py +0 -6
  7. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/cron.py +1 -1
  8. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/fs/_dispatch.py +2 -2
  9. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/fs/cli.py +64 -10
  10. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/runspec.toml +5 -239
  11. runspec_linux-0.19.0/runspec_linux/venvs.py +0 -108
  12. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/_escalation.py +0 -0
  13. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/commands.py +0 -0
  14. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/containers.py +0 -0
  15. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/files.py +0 -0
  16. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/fs/__init__.py +0 -0
  17. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/fs/_worker.py +0 -0
  18. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/investigate.py +0 -0
  19. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/logs.py +0 -0
  20. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/nc_command.py +0 -0
  21. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/network.py +0 -0
  22. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/packages.py +0 -0
  23. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/perf.py +0 -0
  24. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/security.py +0 -0
  25. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/services.py +0 -0
  26. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/system_info.py +0 -0
  27. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/runspec_linux/webops.py +0 -0
  28. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/__init__.py +0 -0
  29. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_escalation.py +0 -0
  30. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_files.py +0 -0
  31. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_fs.py +0 -0
  32. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_inventory.py +0 -0
  33. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_nc_send.py +0 -0
  34. {runspec_linux-0.19.0 → runspec_linux-0.21.0}/tests/test_webops.py +0 -0
@@ -25,6 +25,8 @@ coverage.xml
25
25
  # Node
26
26
  node_modules/
27
27
  dist/
28
+ # runspec manifest output (written at npm pack time)
29
+ runspec-files.json
28
30
  *.js.map
29
31
  .npm
30
32
 
@@ -59,3 +61,6 @@ chainlit-docs/
59
61
 
60
62
  # Stray committed test venv (removed from tracking)
61
63
  .venv-test/
64
+
65
+ # Private gitleaks rules (see .gitleaks.toml)
66
+ .gitleaks.local.toml
@@ -1,5 +1,46 @@
1
1
  # runspec-linux Changelog
2
2
 
3
+ ## [0.21.0] — 2026-11-08
4
+
5
+ ### Added
6
+
7
+ - **`filesystem`: `{{secret:<credential>}}` placeholders in `write-file --content` and
8
+ `edit-file --new-text`.** The value comes from `RUNSPEC_SECRET_<NAME>` in the
9
+ run's environment (runspec-console 0.390.0 sends the named credential on
10
+ stdin when it's allowed into files) and is filled in just before the write —
11
+ before a `--run-as` hand-off, so the worker gets it on stdin, never argv. The
12
+ result, `edit-file`'s diff and errors show the placeholder, never the value;
13
+ the call's args and run record only ever hold the placeholder. A write that
14
+ used a secret records an `fs.secret_written` audit event (path + credential
15
+ ids).
16
+ - **`filesystem`: `--mode`** on `write-file` / `edit-file` (e.g. `0600`, `0640`). A new file
17
+ holding a secret starts `0600`; an existing file keeps its owner and mode
18
+ unless `--mode` is given.
19
+
20
+ ### Changed
21
+
22
+ - Requires `runspec-fs-core >= 0.6.0`.
23
+
24
+ ## [0.20.0] — 2026-10-02
25
+
26
+ **Venv management moved to runspec-console.** Setting up a venv is a console
27
+ job now: runspec-console 0.312.0 provisions a runspec venv on a host from
28
+ **Settings → Jump Hosts → Provision new venv…** (interpreter, location,
29
+ run-as account, packages, logs inbox), and its **Marketplace** tab installs
30
+ into existing venvs. On the command line, plain `python -m venv`,
31
+ `pip install` and `runspec logs share --inbox` do the same job.
32
+
33
+ ### Removed
34
+
35
+ - `create-venv`, `install-into-venv`, `configure-pip` and `share-venv-logs`.
36
+ - The `runspec_linux` re-exports of `create_venv`, `install_into_venv` and
37
+ `configure_pip`. Their helpers are also gone from `runspec-linux-core`
38
+ 0.14.0.
39
+
40
+ Upgrade `runspec-linux` and `runspec-linux-core` together: runspec-linux
41
+ 0.19.0 still imports the removed helpers, so it breaks against
42
+ runspec-linux-core 0.14.0.
43
+
3
44
  ## [0.19.0] — 2026-09-30
4
45
 
5
46
  **No root in runspec-linux.** Everything here now runs as an unprivileged
@@ -1,14 +1,14 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: runspec-linux
3
- Version: 0.19.0
3
+ Version: 0.21.0
4
4
  Summary: Linux system admin runnables for runspec
5
5
  Project-URL: Documentation, https://runspec.app/
6
- Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux
7
- Project-URL: Changelog, https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-linux/CHANGELOG.md
8
- Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
6
+ Project-URL: Source, https://github.com/runspec-app/runspec/tree/main/packages/python/runspec-linux
7
+ Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/packages/python/runspec-linux/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/runspec-app/runspec/issues
9
9
  Keywords: linux,ops,runnable,runspec,ssh,sysadmin,venv
10
10
  Requires-Python: >=3.10
11
- Requires-Dist: runspec-fs-core>=0.5.0
11
+ Requires-Dist: runspec-fs-core>=0.6.0
12
12
  Requires-Dist: runspec-linux-core>=0.13.0
13
13
  Requires-Dist: runspec-webops-core>=0.3.0
14
14
  Requires-Dist: runspec>=0.50.1
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
20
20
 
21
21
  # runspec-linux
22
22
 
23
- Linux system-administration runnables (plus Python-venv management, crontab,
23
+ Linux system-administration runnables (plus crontab,
24
24
  filesystem, and the cross-platform web/TLS/API probes) for
25
25
  [runspec](https://pypi.org/project/runspec/). `pip install` it into a venv and
26
26
  the runnables are discoverable by `runspec local`, `runspec serve` (MCP), and
@@ -57,7 +57,6 @@ pip install runspec-linux
57
57
  | Sessions | `last-logins`, `who` |
58
58
  | Containers | `list-containers`, `container-logs`, `restart-container` |
59
59
  | Packages (read-only) | `list-packages`, `list-autoremovable` |
60
- | Python venvs | `create-venv`, `install-into-venv`, `configure-pip` |
61
60
  | TCP | `nc-command` |
62
61
  | Commands | `which` |
63
62
  | Cron | `cron` (multi-verb: `list`/`add`/`remove`/`clear`) |
@@ -77,14 +76,11 @@ cert-check --url https://internal.example.com
77
76
 
78
77
  ### Python venvs
79
78
 
80
- `create-venv`, `install-into-venv` and `configure-pip` take a **per-invocation**
81
- `--run-as <user>` (+ `--become-method sudo|su`) rather than a declarative
82
- `run_as`, so the service account that owns a shared venv is chosen per call:
83
-
84
- ```
85
- create-venv --python /usr/bin/python3.12 --dest /opt/venvs/ops --run-as svc-ops --group ops
86
- install-into-venv --venv /opt/venvs/ops --package "runspec-linux==0.13.2" --run-as svc-ops
87
- ```
79
+ The venv runnables (`create-venv`, `install-into-venv`, `configure-pip`,
80
+ `share-venv-logs`) were removed in 0.20.0. Provision a venv on a host from
81
+ runspec-console (**Settings → Jump Hosts → Provision new venv…**), install
82
+ packages from its **Marketplace** tab, or on the command line use
83
+ `python -m venv`, `pip install` and `runspec logs share --inbox`.
88
84
 
89
85
  ## Public Python API
90
86
 
@@ -94,7 +90,7 @@ runnables). A corporate wrapper package that only wants a helper should depend
94
90
  on the core alone:
95
91
 
96
92
  ```python
97
- from runspec_linux_core import nc_send, system_info, install_into_venv
93
+ from runspec_linux_core import nc_send, system_info, which
98
94
  ```
99
95
 
100
96
  The helpers are also re-exported from `runspec_linux` for back-compat. Core
@@ -1,6 +1,6 @@
1
1
  # runspec-linux
2
2
 
3
- Linux system-administration runnables (plus Python-venv management, crontab,
3
+ Linux system-administration runnables (plus crontab,
4
4
  filesystem, and the cross-platform web/TLS/API probes) for
5
5
  [runspec](https://pypi.org/project/runspec/). `pip install` it into a venv and
6
6
  the runnables are discoverable by `runspec local`, `runspec serve` (MCP), and
@@ -37,7 +37,6 @@ pip install runspec-linux
37
37
  | Sessions | `last-logins`, `who` |
38
38
  | Containers | `list-containers`, `container-logs`, `restart-container` |
39
39
  | Packages (read-only) | `list-packages`, `list-autoremovable` |
40
- | Python venvs | `create-venv`, `install-into-venv`, `configure-pip` |
41
40
  | TCP | `nc-command` |
42
41
  | Commands | `which` |
43
42
  | Cron | `cron` (multi-verb: `list`/`add`/`remove`/`clear`) |
@@ -57,14 +56,11 @@ cert-check --url https://internal.example.com
57
56
 
58
57
  ### Python venvs
59
58
 
60
- `create-venv`, `install-into-venv` and `configure-pip` take a **per-invocation**
61
- `--run-as <user>` (+ `--become-method sudo|su`) rather than a declarative
62
- `run_as`, so the service account that owns a shared venv is chosen per call:
63
-
64
- ```
65
- create-venv --python /usr/bin/python3.12 --dest /opt/venvs/ops --run-as svc-ops --group ops
66
- install-into-venv --venv /opt/venvs/ops --package "runspec-linux==0.13.2" --run-as svc-ops
67
- ```
59
+ The venv runnables (`create-venv`, `install-into-venv`, `configure-pip`,
60
+ `share-venv-logs`) were removed in 0.20.0. Provision a venv on a host from
61
+ runspec-console (**Settings → Jump Hosts → Provision new venv…**), install
62
+ packages from its **Marketplace** tab, or on the command line use
63
+ `python -m venv`, `pip install` and `runspec logs share --inbox`.
68
64
 
69
65
  ## Public Python API
70
66
 
@@ -74,7 +70,7 @@ runnables). A corporate wrapper package that only wants a helper should depend
74
70
  on the core alone:
75
71
 
76
72
  ```python
77
- from runspec_linux_core import nc_send, system_info, install_into_venv
73
+ from runspec_linux_core import nc_send, system_info, which
78
74
  ```
79
75
 
80
76
  The helpers are also re-exported from `runspec_linux` for back-compat. Core
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "runspec-linux"
7
- version = "0.19.0"
7
+ version = "0.21.0"
8
8
  requires-python = ">=3.10"
9
9
  description = "Linux system admin runnables for runspec"
10
10
  readme = "README.md"
@@ -13,14 +13,14 @@ dependencies = [
13
13
  "runspec>=0.50.1",
14
14
  "runspec-linux-core>=0.13.0",
15
15
  "runspec-webops-core>=0.3.0",
16
- "runspec-fs-core>=0.5.0",
16
+ "runspec-fs-core>=0.6.0",
17
17
  ]
18
18
 
19
19
  [project.urls]
20
20
  Documentation = "https://runspec.app/"
21
- Source = "https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux"
22
- Changelog = "https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-linux/CHANGELOG.md"
23
- Issues = "https://github.com/jasonfinestone/runspec/issues"
21
+ Source = "https://github.com/runspec-app/runspec/tree/main/packages/python/runspec-linux"
22
+ Changelog = "https://github.com/runspec-app/runspec/blob/main/packages/python/runspec-linux/CHANGELOG.md"
23
+ Issues = "https://github.com/runspec-app/runspec/issues"
24
24
 
25
25
  [project.scripts]
26
26
  system-info = "runspec_linux.system_info:main_system_info"
@@ -58,10 +58,6 @@ container-logs = "runspec_linux.containers:main_container_logs"
58
58
  restart-container = "runspec_linux.containers:main_restart_container"
59
59
  list-packages = "runspec_linux.packages:main_list_packages"
60
60
  list-autoremovable = "runspec_linux.packages:main_list_autoremovable"
61
- create-venv = "runspec_linux.venvs:main_create_venv"
62
- install-into-venv = "runspec_linux.venvs:main_install_into_venv"
63
- configure-pip = "runspec_linux.venvs:main_configure_pip"
64
- share-venv-logs = "runspec_linux.venvs:main_share_venv_logs"
65
61
  nc-command = "runspec_linux.nc_command:main"
66
62
  which = "runspec_linux.commands:main_which"
67
63
  # Cron / crontab management (backed by runspec-linux-core)
@@ -15,13 +15,10 @@ from runspec_linux_core import (
15
15
  check_port,
16
16
  check_service,
17
17
  clear_cron,
18
- configure_pip,
19
18
  container_logs,
20
- create_venv,
21
19
  detect_manager,
22
20
  disk_usage,
23
21
  find_large_files,
24
- install_into_venv,
25
22
  journalctl,
26
23
  last_logins,
27
24
  list_containers,
@@ -49,13 +46,10 @@ __all__ = [
49
46
  "check_port",
50
47
  "check_service",
51
48
  "clear_cron",
52
- "configure_pip",
53
49
  "container_logs",
54
- "create_venv",
55
50
  "detect_manager",
56
51
  "disk_usage",
57
52
  "find_large_files",
58
- "install_into_venv",
59
53
  "journalctl",
60
54
  "last_logins",
61
55
  "list_containers",
@@ -7,7 +7,7 @@ merged ``[cron]`` tables in the pack's ``runspec.toml``); we unpack each
7
7
  helper, which does the crontab read-modify-write.
8
8
 
9
9
  **Per-invocation ``--run-as``** (a global arg inherited by every verb, like the
10
- venv runnables): the operator/agent picks whose crontab to manage per call. The
10
+ container runnables): the operator/agent picks whose crontab to manage per call. The
11
11
  ``crontab`` command is escalated via ``sudo -n -u <user>`` / ``su`` inside the
12
12
  core helper, so "run as user *bob*" means "manage *bob*'s crontab". With no
13
13
  ``--run-as`` the caller's own crontab is used.
@@ -55,10 +55,10 @@ def run_verb(verb: str, kwargs: dict[str, Any]) -> dict[str, Any]:
55
55
  if verb == "list-allowed-directories":
56
56
  return allowed_directories()
57
57
  if verb == "write-file":
58
- return write_file(kwargs["path"], kwargs["content"])
58
+ return write_file(kwargs["path"], kwargs["content"], mode=kwargs.get("mode"), private=kwargs.get("private", False))
59
59
  if verb == "edit-file":
60
60
  edits = [tuple(pair) for pair in kwargs["edits"]]
61
- return edit_file(kwargs["path"], edits, dry_run=kwargs["dry_run"])
61
+ return edit_file(kwargs["path"], edits, dry_run=kwargs["dry_run"], mode=kwargs.get("mode"), private=kwargs.get("private", False))
62
62
  if verb == "create-directory":
63
63
  return create_directory(kwargs["path"])
64
64
  if verb == "move-file":
@@ -18,13 +18,23 @@ import paths; the logic is the shared ``runspec_fs_core``.
18
18
 
19
19
  from __future__ import annotations
20
20
 
21
+ import contextlib
21
22
  import json
22
23
  import subprocess
23
24
  import sys
24
25
  from typing import Any
25
26
 
26
27
  import runspec as rs
27
- from runspec_fs_core import BecomeError, FsCoreError, build_become, current_user, escalation_supported
28
+ from runspec_fs_core import (
29
+ BecomeError,
30
+ FsCoreError,
31
+ build_become,
32
+ current_user,
33
+ escalation_supported,
34
+ fill_verb_secrets,
35
+ mask_secrets,
36
+ mask_text,
37
+ )
28
38
 
29
39
  from runspec_linux._escalation import refuse_root
30
40
  from runspec_linux.fs._dispatch import run_verb
@@ -42,6 +52,31 @@ def _pair_edits(old_text: list[str], new_text: list[str]) -> list[list[str]]:
42
52
  return [[old, new] for old, new in zip(old_text, new_text, strict=False)]
43
53
 
44
54
 
55
+ def _octal(mode: str | None) -> int | None:
56
+ """``--mode 0640`` -> ``0o640`` (``None`` when unset)."""
57
+ if not mode:
58
+ return None
59
+ try:
60
+ return int(mode, 8)
61
+ except ValueError:
62
+ raise ValueError(f"--mode must be octal permissions like 0600 or 0640, got {mode!r}") from None
63
+
64
+
65
+ def _audit_secret_write(verb: str, kwargs: dict[str, Any], credential_ids: list[str], outcome: str) -> None:
66
+ """One ``fs.secret_written`` audit event when the text held ``{{secret:…}}``
67
+ placeholders: the path and credential ids, never the values."""
68
+ if not credential_ids:
69
+ return
70
+ # The audit must never break the write's own result.
71
+ with contextlib.suppress(Exception):
72
+ rs.audit(
73
+ "fs.secret_written",
74
+ outcome,
75
+ target={"path": str(kwargs.get("path", ""))},
76
+ detail={"verb": verb, "credentials": credential_ids, "dry_run": bool(kwargs.get("dry_run"))},
77
+ )
78
+
79
+
45
80
  def _verb_kwargs(spec: rs.RunSpec) -> dict[str, Any]:
46
81
  """Unpack the parsed spec into a plain, JSON-round-trip-safe kwargs dict for
47
82
  the active verb (paths as strings), so the same dict serves the in-process
@@ -69,12 +104,13 @@ def _verb_kwargs(spec: rs.RunSpec) -> dict[str, Any]:
69
104
  if command == "list-allowed-directories":
70
105
  return {}
71
106
  if command == "write-file":
72
- return {"path": str(spec.path.value), "content": spec.content.value}
107
+ return {"path": str(spec.path.value), "content": spec.content.value, "mode": _octal(spec.mode.value)}
73
108
  if command == "edit-file":
74
109
  return {
75
110
  "path": str(spec.path.value),
76
111
  "edits": _pair_edits(spec.old_text.value, spec.new_text.value),
77
112
  "dry_run": spec.dry_run.value,
113
+ "mode": _octal(spec.mode.value),
78
114
  }
79
115
  if command == "create-directory":
80
116
  return {"path": str(spec.path.value)}
@@ -85,7 +121,7 @@ def _verb_kwargs(spec: rs.RunSpec) -> dict[str, Any]:
85
121
  raise SystemExit("no command — see `filesystem --help`") # pragma: no cover
86
122
 
87
123
 
88
- def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any]) -> str:
124
+ def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any], masks: dict[str, str] | None = None) -> str:
89
125
  """Re-invoke the verb as ``run_as`` via the worker under sudo/su and return
90
126
  its stdout. Raises :class:`BecomeError` on an escalation failure (a
91
127
  passwordless-sudo hint on the classic cases)."""
@@ -107,7 +143,7 @@ def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any])
107
143
  # it through with the worker's exit code rather than masking it.
108
144
  out = (proc.stdout or "").strip()
109
145
  if out:
110
- print(out)
146
+ print(mask_text(out, masks or {}))
111
147
  sys.exit(proc.returncode)
112
148
  raise BecomeError(err or f"run-as {run_as!r} failed (exit {proc.returncode})")
113
149
  return proc.stdout
@@ -116,19 +152,37 @@ def _run_as_worker(run_as: str, method: str, verb: str, kwargs: dict[str, Any])
116
152
  def main() -> None:
117
153
  spec = rs.parse("filesystem")
118
154
  run_as = spec.run_as.value
119
- refuse_root(run_as or None)
120
155
  method = spec.become_method.value
156
+ refuse_root(run_as or None)
157
+ verb = spec.runspec_command
158
+ # `request` is the call as given (placeholders, never values) — the audit
159
+ # record reads only that. `kwargs` is what the verb runs with.
160
+ request: dict[str, Any] = {}
161
+ masks: dict[str, str] = {}
162
+ credential_ids: list[str] = []
121
163
  try:
122
- kwargs = _verb_kwargs(spec)
164
+ request = _verb_kwargs(spec)
165
+ # {{secret:<id>}} placeholders are filled here, before any --run-as
166
+ # hand-off (sudo drops the environment; the worker gets the filled text
167
+ # on stdin). The values are masked back out of everything printed.
168
+ kwargs, masks, credential_ids = fill_verb_secrets(verb, request)
123
169
  if run_as and run_as != current_user():
124
- out = _run_as_worker(run_as, method, spec.runspec_command, kwargs)
170
+ try:
171
+ out = _run_as_worker(run_as, method, verb, kwargs, masks)
172
+ except SystemExit:
173
+ _audit_secret_write(verb, request, credential_ids, "failed")
174
+ raise
175
+ _audit_secret_write(verb, request, credential_ids, "succeeded")
176
+ out = mask_text(out, masks)
125
177
  sys.stdout.write(out if out.endswith("\n") else out + "\n")
126
178
  return
127
- result = run_verb(spec.runspec_command, kwargs)
179
+ result = run_verb(verb, kwargs)
128
180
  except (FsCoreError, OSError, ValueError) as exc:
129
- _emit({"error": str(exc), "kind": type(exc).__name__})
181
+ _audit_secret_write(verb, request, credential_ids, "failed")
182
+ _emit(mask_secrets({"error": str(exc), "kind": type(exc).__name__}, masks))
130
183
  sys.exit(1)
131
- _emit(result)
184
+ _audit_secret_write(verb, request, credential_ids, "succeeded")
185
+ _emit(mask_secrets(result, masks))
132
186
 
133
187
 
134
188
  if __name__ == "__main__":
@@ -500,242 +500,6 @@ type = "str"
500
500
  description = "Override the search PATH to use (defaults to the host's $PATH)"
501
501
  required = false
502
502
 
503
- # ── Python venvs ──────────────────────────────────────────────────────────────
504
-
505
- # These deliberately declare NO `run_as` key. The service account that owns a
506
- # shared venv is chosen per invocation, so each runnable takes a `run-as`
507
- # argument and escalates internally (`sudo -n -u <user>`, or `su` via
508
- # `become-method`). An empty `run-as` runs as the SSH login user (personal venv).
509
-
510
- [create-venv]
511
- serve = ["local"]
512
- description = "Create a Python virtualenv (always --symlinks) from a specific interpreter, optionally as a service account, with a logs inbox so every account's runs reach its history"
513
- autonomy = "confirm"
514
- output = "json"
515
-
516
- [create-venv.args.python]
517
- type = "path"
518
- description = "Path to the Python interpreter to build the venv from (browse to a real binary — not the system default)"
519
-
520
- [create-venv.args.dest]
521
- type = "path"
522
- short = "-d"
523
- description = "Full path of the venv to create (name and location are free)"
524
-
525
- [create-venv.args.run-as]
526
- type = "str"
527
- short = "-u"
528
- description = "Service account to create the venv as (escalates via sudo/su); empty = the SSH login user"
529
- required = false
530
-
531
- [create-venv.args.become-method]
532
- type = "choice"
533
- options = ["sudo", "su"]
534
- default = "sudo"
535
- description = "How to escalate to run-as: sudo (passwordless, -n) or su"
536
-
537
- [create-venv.args.group]
538
- type = "str"
539
- short = "-g"
540
- description = "Optional shared group to chgrp the venv to (e.g. consoles), so every connected console can read/write"
541
- required = false
542
-
543
- [create-venv.args.no-inbox]
544
- type = "flag"
545
- description = "Don't set up the logs inbox (logs/inbox, 01777) — keep the pre-inbox layout (logs/ 2775) and write a logs/.no-inbox opt-out marker. Default: the inbox is created, so operators' and root's runs reach this venv's history with no group admin (runspec >= 0.66)"
546
- default = false
547
-
548
- [create-venv.args.system-site-packages]
549
- type = "flag"
550
- description = "Give the venv access to the system site-packages"
551
- default = false
552
-
553
- [create-venv.args.upgrade-deps]
554
- type = "flag"
555
- description = "Upgrade pip/setuptools to the latest in the new venv (--upgrade-deps)"
556
- default = false
557
-
558
- [create-venv.args.clear]
559
- type = "flag"
560
- description = "Delete the contents of the venv directory if it already exists (--clear)"
561
- default = false
562
-
563
- [create-venv.args.prompt]
564
- type = "str"
565
- short = "-p"
566
- description = "Prompt prefix shown when the venv is activated (--prompt)"
567
- required = false
568
-
569
- [install-into-venv]
570
- serve = ["local"]
571
- description = "pip install named packages and/or a local project (pyproject dir or wheel/sdist) into an existing venv"
572
- autonomy = "confirm"
573
- output = "json"
574
-
575
- [install-into-venv.args.venv]
576
- type = "path"
577
- ui = "directory"
578
- short = "-v"
579
- description = "Path to the venv to install into (its bundled python runs pip)"
580
-
581
- [install-into-venv.args.package]
582
- type = "str"
583
- short = "-p"
584
- description = "Package spec(s) to install (space-separated for several)"
585
- required = false
586
-
587
- [install-into-venv.args.project]
588
- type = "path"
589
- description = "Path to a local project to install — a directory with pyproject.toml, or a wheel/sdist"
590
- required = false
591
-
592
- [install-into-venv.args.editable]
593
- type = "flag"
594
- short = "-e"
595
- description = "Install the project in editable mode (pip install -e); requires --project"
596
- default = false
597
-
598
- [install-into-venv.args.upgrade]
599
- type = "flag"
600
- short = "-U"
601
- description = "Upgrade packages to the newest available version (pip install -U)"
602
- default = false
603
-
604
- [install-into-venv.args.no-cache-dir]
605
- type = "flag"
606
- description = "Disable the pip cache for this install (--no-cache-dir)"
607
- default = false
608
-
609
- [install-into-venv.args.force-reinstall]
610
- type = "flag"
611
- description = "Reinstall packages even if already up to date (--force-reinstall)"
612
- default = false
613
-
614
- [install-into-venv.args.run-as]
615
- type = "str"
616
- short = "-u"
617
- description = "Service account that owns the venv (escalates via sudo/su); empty = the SSH login user"
618
- required = false
619
-
620
- [install-into-venv.args.become-method]
621
- type = "choice"
622
- options = ["sudo", "su"]
623
- default = "sudo"
624
- description = "How to escalate to run-as: sudo (passwordless, -n) or su"
625
-
626
- [configure-pip]
627
- serve = ["local"]
628
- description = "Write a pip.conf (index-url and friends) at user or venv scope for private-PyPI access"
629
- autonomy = "confirm"
630
- output = "json"
631
-
632
- [configure-pip.args.index-url]
633
- type = "str"
634
- short = "-i"
635
- description = "Primary package index URL (index-url)"
636
-
637
- [configure-pip.args.extra-index-url]
638
- type = "str"
639
- description = "Additional package index URL (extra-index-url)"
640
- required = false
641
-
642
- [configure-pip.args.trusted-host]
643
- type = "str"
644
- description = "Host to trust without TLS verification (trusted-host)"
645
- required = false
646
-
647
- [configure-pip.args.cert]
648
- type = "str"
649
- description = "Path to a CA bundle to verify the index's TLS certificate (cert)"
650
- required = false
651
-
652
- [configure-pip.args.timeout]
653
- type = "int"
654
- description = "Socket timeout in seconds (timeout)"
655
- required = false
656
-
657
- [configure-pip.args.retries]
658
- type = "int"
659
- description = "Number of retries for a failed connection (retries)"
660
- required = false
661
-
662
- [configure-pip.args.proxy]
663
- type = "str"
664
- description = "Proxy URL in [user:passwd@]proxy.server:port form (proxy)"
665
- required = false
666
-
667
- [configure-pip.args.require-virtualenv]
668
- type = "flag"
669
- description = "Refuse to install outside a virtualenv and silence the pip-version check (require-virtualenv + disable-pip-version-check)"
670
- default = false
671
-
672
- [configure-pip.args.scope]
673
- type = "choice"
674
- options = ["user", "venv"]
675
- default = "user"
676
- short = "-s"
677
- description = "Where to write pip.conf: user (~/.config/pip/pip.conf) or venv (<venv>/pip.conf)"
678
-
679
- [configure-pip.args.venv]
680
- type = "path"
681
- ui = "directory"
682
- description = "Venv path for --scope venv (the file is written to <venv>/pip.conf)"
683
- required = false
684
-
685
- [configure-pip.args.run-as]
686
- type = "str"
687
- short = "-u"
688
- description = "User who owns the target file (escalates via sudo/su); empty = the SSH login user"
689
- required = false
690
-
691
- [configure-pip.args.become-method]
692
- type = "choice"
693
- options = ["sudo", "su"]
694
- default = "sudo"
695
- description = "How to escalate to run-as: sudo (passwordless, -n) or su"
696
-
697
- [share-venv-logs]
698
- serve = ["local"]
699
- description = "Make an existing venv's logs shared: set up the logs inbox (logs/inbox, 01777) so every account's runs reach its history — plus, with --group, the 2775 setgid group share. Run as the venv owner (--run-as)"
700
- autonomy = "confirm"
701
- output = "json"
702
-
703
- examples = [
704
- {cmd = "share-venv-logs --venv /opt/venvs/app --run-as svc", description = "Set up the logs inbox as the venv's owner — the recommended setup"},
705
- {cmd = "share-venv-logs --venv /opt/venvs/app --no-inbox", description = "The pre-inbox group share only: logs/ group-writable + setgid"},
706
- {cmd = "share-venv-logs --venv /opt/venvs/app --group consoles", description = "...and chgrp the logs dir to the shared 'consoles' group"},
707
- {cmd = "share-venv-logs --venv /opt/venvs/app --group consoles --run-as svc", description = "Run as the service account that owns the venv (via sudo -n -u)"},
708
- ]
709
-
710
- [share-venv-logs.args.venv]
711
- type = "path"
712
- ui = "directory"
713
- short = "-v"
714
- description = "Path to the existing venv whose logs/ dir should be made shared"
715
-
716
- [share-venv-logs.args.group]
717
- type = "str"
718
- short = "-g"
719
- description = "Optional shared group to chgrp the logs/ dir to (e.g. consoles), so every connected console can read/write. Omit to keep the current group"
720
- required = false
721
-
722
- [share-venv-logs.args.no-inbox]
723
- type = "flag"
724
- description = "Skip the logs inbox — only the group share (logs/ 2775 setgid, optional chgrp)"
725
- default = false
726
-
727
- [share-venv-logs.args.run-as]
728
- type = "str"
729
- short = "-u"
730
- description = "Service account that owns the venv (escalates via sudo/su); empty = the SSH login user"
731
- required = false
732
-
733
- [share-venv-logs.args.become-method]
734
- type = "choice"
735
- options = ["sudo", "su"]
736
- default = "sudo"
737
- description = "How to escalate to run-as: sudo (passwordless, -n) or su"
738
-
739
503
  # ── Web / TLS probes (runspec-webops-core; cross-platform, read-only) ──────────
740
504
 
741
505
  [cert-check]
@@ -1294,20 +1058,22 @@ autonomy = "autonomous"
1294
1058
  # ── mutations → confirm ────────────────────────────────────────────────────
1295
1059
 
1296
1060
  [filesystem.commands.write-file]
1297
- description = "Create a new file or overwrite an existing one with UTF-8 text"
1061
+ description = "Create a new file or overwrite an existing one with UTF-8 text. Text may hold {{secret:<credential id>}} (or {{secret:<id>.username}}) placeholders: the value is filled in on the host just before writing and never appears in the call, its output or the run record. runspec-console sends the named saved credential; from a shell, set RUNSPEC_SECRET_<ID> (id upper-cased, other characters as _). A new file holding a secret is created 0600 unless --mode says otherwise."
1298
1062
  autonomy = "confirm"
1299
1063
  [filesystem.commands.write-file.args]
1300
1064
  path = {type = "path", required = true, description = "File to write"}
1301
- content = {type = "str", required = true, description = "File contents"}
1065
+ content = {type = "str", required = true, description = "File contents (may hold {{secret:<credential id>}} placeholders)"}
1066
+ mode = {type = "str", required = false, pattern = "^0?[0-7]{3,4}$", description = "Octal permissions to set before writing, e.g. 0600 (owner only) or 0640 (owner + group, for a service that reads the file through its group). An existing file otherwise keeps its owner and mode; a new one holding a secret starts at 0600."}
1302
1067
 
1303
1068
  [filesystem.commands.edit-file]
1304
- description = "Apply ordered old→new substring replacements to a file; returns a unified diff. Pair each --old-text with a --new-text by position."
1069
+ description = "Apply ordered old→new substring replacements to a file; returns a unified diff. Pair each --old-text with a --new-text by position. New text may hold {{secret:<credential id>}} placeholders (see write-file); filled values are shown as the placeholder in the diff."
1305
1070
  autonomy = "confirm"
1306
1071
  [filesystem.commands.edit-file.args]
1307
1072
  path = {type = "path", required = true, description = "File to edit"}
1308
1073
  old-text = {type = "str", multiple = true, required = true, description = "Text to find (repeat --old-text; paired by position with --new-text)"}
1309
1074
  new-text = {type = "str", multiple = true, required = true, description = "Replacement text (repeat --new-text; paired by position with --old-text)"}
1310
1075
  dry-run = {type = "flag", default = false, description = "Compute and diff the edits without writing"}
1076
+ mode = {type = "str", required = false, pattern = "^0?[0-7]{3,4}$", description = "Octal permissions to set before writing, e.g. 0600 (owner only) or 0640 (owner + group, for a service that reads the file through its group). An existing file otherwise keeps its owner and mode; a new one holding a secret starts at 0600."}
1311
1077
 
1312
1078
  [filesystem.commands.create-directory]
1313
1079
  description = "Create a directory (and any missing parents); idempotent"
@@ -1,108 +0,0 @@
1
- import json
2
- import sys
3
-
4
- import runspec as rs
5
- from runspec_linux_core import configure_pip, create_venv, install_into_venv, share_venv_logs
6
- from runspec_linux_core.errors import CommandError
7
-
8
- from runspec_linux._escalation import refuse_root
9
-
10
-
11
- def main_create_venv() -> None:
12
- spec = rs.parse("create-venv")
13
- refuse_root(spec.run_as.value or None)
14
- try:
15
- result = create_venv(
16
- str(spec.python.value),
17
- str(spec.dest.value),
18
- run_as=spec.run_as.value or None,
19
- become_method=spec.become_method.value,
20
- group=spec.group.value or None,
21
- system_site_packages=spec.system_site_packages.value,
22
- upgrade_deps=spec.upgrade_deps.value,
23
- clear=spec.clear.value,
24
- prompt=spec.prompt.value or None,
25
- inbox=not spec.no_inbox.value,
26
- )
27
- print(json.dumps(result))
28
- except CommandError as e:
29
- print(json.dumps({"dest": str(spec.dest.value), "created": False, "error": str(e)}))
30
- sys.exit(1)
31
- except Exception as e:
32
- # Includes ValueError (non-executable interpreter / bad name).
33
- print(json.dumps({"error": str(e)}))
34
- sys.exit(1)
35
-
36
-
37
- def main_install_into_venv() -> None:
38
- spec = rs.parse("install-into-venv")
39
- refuse_root(spec.run_as.value or None)
40
- try:
41
- result = install_into_venv(
42
- str(spec.venv.value),
43
- spec.package.value or "",
44
- project=str(spec.project.value) if spec.project.value else None,
45
- editable=spec.editable.value,
46
- upgrade=spec.upgrade.value,
47
- no_cache_dir=spec.no_cache_dir.value,
48
- force_reinstall=spec.force_reinstall.value,
49
- run_as=spec.run_as.value or None,
50
- become_method=spec.become_method.value,
51
- )
52
- print(json.dumps(result))
53
- except CommandError as e:
54
- print(json.dumps({"venv": str(spec.venv.value), "installed": False, "error": str(e)}))
55
- sys.exit(1)
56
- except Exception as e:
57
- # Includes ValueError (bad package name / missing venv / nothing to install).
58
- print(json.dumps({"error": str(e)}))
59
- sys.exit(1)
60
-
61
-
62
- def main_share_venv_logs() -> None:
63
- spec = rs.parse("share-venv-logs")
64
- refuse_root(spec.run_as.value or None)
65
- try:
66
- result = share_venv_logs(
67
- str(spec.venv.value),
68
- group=spec.group.value or None,
69
- run_as=spec.run_as.value or None,
70
- become_method=spec.become_method.value,
71
- inbox=not spec.no_inbox.value,
72
- )
73
- print(json.dumps(result))
74
- except CommandError as e:
75
- print(json.dumps({"venv": str(spec.venv.value), "shared": False, "error": str(e)}))
76
- sys.exit(1)
77
- except Exception as e:
78
- # Includes ValueError (bad venv path / group name).
79
- print(json.dumps({"error": str(e)}))
80
- sys.exit(1)
81
-
82
-
83
- def main_configure_pip() -> None:
84
- spec = rs.parse("configure-pip")
85
- refuse_root(spec.run_as.value or None)
86
- try:
87
- result = configure_pip(
88
- spec.index_url.value,
89
- extra_index_url=spec.extra_index_url.value or None,
90
- trusted_host=spec.trusted_host.value or None,
91
- cert=spec.cert.value or None,
92
- timeout=spec.timeout.value,
93
- retries=spec.retries.value,
94
- proxy=spec.proxy.value or None,
95
- require_virtualenv=spec.require_virtualenv.value,
96
- scope=spec.scope.value,
97
- venv=str(spec.venv.value) if spec.venv.value else None,
98
- run_as=spec.run_as.value or None,
99
- become_method=spec.become_method.value,
100
- )
101
- print(json.dumps(result))
102
- except CommandError as e:
103
- print(json.dumps({"configured": False, "error": str(e)}))
104
- sys.exit(1)
105
- except Exception as e:
106
- # Includes ValueError (bad scope / missing venv path).
107
- print(json.dumps({"error": str(e)}))
108
- sys.exit(1)