runspec-linux 0.20.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 (33) hide show
  1. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/.gitignore +5 -0
  2. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/CHANGELOG.md +21 -0
  3. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/PKG-INFO +5 -5
  4. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/pyproject.toml +5 -5
  5. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/fs/_dispatch.py +2 -2
  6. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/fs/cli.py +64 -10
  7. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/runspec.toml +5 -3
  8. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/README.md +0 -0
  9. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/__init__.py +0 -0
  10. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/_escalation.py +0 -0
  11. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/commands.py +0 -0
  12. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/containers.py +0 -0
  13. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/cron.py +0 -0
  14. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/files.py +0 -0
  15. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/fs/__init__.py +0 -0
  16. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/fs/_worker.py +0 -0
  17. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/investigate.py +0 -0
  18. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/logs.py +0 -0
  19. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/nc_command.py +0 -0
  20. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/network.py +0 -0
  21. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/packages.py +0 -0
  22. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/perf.py +0 -0
  23. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/security.py +0 -0
  24. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/services.py +0 -0
  25. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/system_info.py +0 -0
  26. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/runspec_linux/webops.py +0 -0
  27. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/__init__.py +0 -0
  28. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/test_escalation.py +0 -0
  29. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/test_files.py +0 -0
  30. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/test_fs.py +0 -0
  31. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/test_inventory.py +0 -0
  32. {runspec_linux-0.20.0 → runspec_linux-0.21.0}/tests/test_nc_send.py +0 -0
  33. {runspec_linux-0.20.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,26 @@
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
+
3
24
  ## [0.20.0] — 2026-10-02
4
25
 
5
26
  **Venv management moved to runspec-console.** Setting up a venv is a console
@@ -1,14 +1,14 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: runspec-linux
3
- Version: 0.20.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
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "runspec-linux"
7
- version = "0.20.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"
@@ -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__":
@@ -1058,20 +1058,22 @@ autonomy = "autonomous"
1058
1058
  # ── mutations → confirm ────────────────────────────────────────────────────
1059
1059
 
1060
1060
  [filesystem.commands.write-file]
1061
- 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."
1062
1062
  autonomy = "confirm"
1063
1063
  [filesystem.commands.write-file.args]
1064
1064
  path = {type = "path", required = true, description = "File to write"}
1065
- 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."}
1066
1067
 
1067
1068
  [filesystem.commands.edit-file]
1068
- 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."
1069
1070
  autonomy = "confirm"
1070
1071
  [filesystem.commands.edit-file.args]
1071
1072
  path = {type = "path", required = true, description = "File to edit"}
1072
1073
  old-text = {type = "str", multiple = true, required = true, description = "Text to find (repeat --old-text; paired by position with --new-text)"}
1073
1074
  new-text = {type = "str", multiple = true, required = true, description = "Replacement text (repeat --new-text; paired by position with --old-text)"}
1074
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."}
1075
1077
 
1076
1078
  [filesystem.commands.create-directory]
1077
1079
  description = "Create a directory (and any missing parents); idempotent"
File without changes