pip-vm-hostrun 0.1.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.
@@ -0,0 +1,69 @@
1
+ Metadata-Version: 2.4
2
+ Name: pip-vm-hostrun
3
+ Version: 0.1.0
4
+ Summary: Run commands on the host from inside a jail (a VM or container), through one unix socket, with a policy and your approval
5
+ Author: readwithai
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+
9
+ # pip-vm-hostrun
10
+ Run commands **on the host** from inside a jail (a VM or a container), from Python or the command line. Outside a jail it just runs the command. Sudo-like rules, kept on the host, define which commands are allowed.
11
+
12
+ Designed for use with pip-vm, but any jail runner can use it.
13
+
14
+ Communication is done through one unix socket, with a policy file and your approval. Standard library only.
15
+
16
+ Outside a jail, `hostrun ls` just runs `ls`. Inside one, the same call goes to a server on
17
+ the host, which decides whether to run it. So a tool can be written once and work both ways.
18
+
19
+ # in the jail (a tool, or the shell)
20
+ hostrun podman ps
21
+ python -c "from pip_vm_hostrun import output; print(output(['id', '-u']))"
22
+
23
+ # on the host
24
+ pip-vm-hostrun serve TOOL
25
+
26
+ ## How it works
27
+
28
+ - **The socket is the identity.** `pip-vm-hostrun serve TOOL` listens on
29
+ `$XDG_RUNTIME_DIR/pip-vm/TOOL/hostrun.sock`, the tool's pip-vm communication directory, which is
30
+ the only thing shared with that jail (mounted at `/run/pip-vm`, with `PIP_VM_COMM=/run/pip-vm`).
31
+ One server per jail; its policy is `~/.config/pip-vm/hostrun/TOOL.policy`.
32
+ The jail is "jailed" when `PIP_VM_COMM` or `HOSTRUN_SOCKET` is set. If it is jailed and there is no
33
+ server, you get an error, never a silent local run.
34
+ - **Only an argv crosses.** A list of strings: no shell, no environment, no working directory.
35
+ The command runs as you, with the server's environment. Output and the exit status stream back.
36
+ - **A policy decides**, first match wins, and a command that matches nothing is *asked about*:
37
+
38
+ allow podman ps ...
39
+ ask sudo iw phy * set netns *
40
+ deny sudo ...
41
+
42
+ Each word is an fnmatch glob for the argv word in that position (`*` never spans words), and a
43
+ final `...` means "and anything after". `allow` needs at least one word, so it cannot be written
44
+ as allow-everything by accident.
45
+ - **Asking** shows the exact argv, shell-quoted (unprintable characters spelled out), on the
46
+ server's terminal: `[y]es once / [a]lways this exact command / [N]o`. `always` appends an exact
47
+ rule to the policy file. `--approve-cmd COMMAND` asks by running your own command with the
48
+ argv as its one argument (exit 0 = yes), for a popup or notification.
49
+ - **Limits:** request size, argument count, output (64 MiB) and a run time (`--timeout`, 300 s).
50
+ The socket is mode 0600 in a 0700 directory; the server refuses a directory that is not yours
51
+ and private. File descriptors sent over the socket are ignored.
52
+
53
+ ## Python
54
+
55
+ from pip_vm_hostrun import run, call, output, Denied, HostrunError
56
+
57
+ run(["podman", "ps"], capture_output=True, text=True, check=True) # like subprocess.run
58
+ call(["sudo", "iw", "phy", "phy1", "set", "netns", "1234"]) # exit status; output passes through
59
+ output(["id", "-u"]) # stdout as text; raises if it fails
60
+
61
+ `Denied` means the host said no. `HostrunError` covers everything else (no server, too long, timed out).
62
+
63
+ ## What this is not
64
+
65
+ It is a narrow, audited doorway, not a sandbox. Whatever you allow runs with your full
66
+ privileges, so allow exact commands, not interpreters or `sh -c`.
67
+
68
+ pip-vm is the QEMU/podman jail runner this was written for. hostrun does not depend on it: any
69
+ jail that shares a directory and sets `HOSTRUN_SOCKET` to the socket inside it will work.
@@ -0,0 +1,61 @@
1
+ # pip-vm-hostrun
2
+ Run commands **on the host** from inside a jail (a VM or a container), from Python or the command line. Outside a jail it just runs the command. Sudo-like rules, kept on the host, define which commands are allowed.
3
+
4
+ Designed for use with pip-vm, but any jail runner can use it.
5
+
6
+ Communication is done through one unix socket, with a policy file and your approval. Standard library only.
7
+
8
+ Outside a jail, `hostrun ls` just runs `ls`. Inside one, the same call goes to a server on
9
+ the host, which decides whether to run it. So a tool can be written once and work both ways.
10
+
11
+ # in the jail (a tool, or the shell)
12
+ hostrun podman ps
13
+ python -c "from pip_vm_hostrun import output; print(output(['id', '-u']))"
14
+
15
+ # on the host
16
+ pip-vm-hostrun serve TOOL
17
+
18
+ ## How it works
19
+
20
+ - **The socket is the identity.** `pip-vm-hostrun serve TOOL` listens on
21
+ `$XDG_RUNTIME_DIR/pip-vm/TOOL/hostrun.sock`, the tool's pip-vm communication directory, which is
22
+ the only thing shared with that jail (mounted at `/run/pip-vm`, with `PIP_VM_COMM=/run/pip-vm`).
23
+ One server per jail; its policy is `~/.config/pip-vm/hostrun/TOOL.policy`.
24
+ The jail is "jailed" when `PIP_VM_COMM` or `HOSTRUN_SOCKET` is set. If it is jailed and there is no
25
+ server, you get an error, never a silent local run.
26
+ - **Only an argv crosses.** A list of strings: no shell, no environment, no working directory.
27
+ The command runs as you, with the server's environment. Output and the exit status stream back.
28
+ - **A policy decides**, first match wins, and a command that matches nothing is *asked about*:
29
+
30
+ allow podman ps ...
31
+ ask sudo iw phy * set netns *
32
+ deny sudo ...
33
+
34
+ Each word is an fnmatch glob for the argv word in that position (`*` never spans words), and a
35
+ final `...` means "and anything after". `allow` needs at least one word, so it cannot be written
36
+ as allow-everything by accident.
37
+ - **Asking** shows the exact argv, shell-quoted (unprintable characters spelled out), on the
38
+ server's terminal: `[y]es once / [a]lways this exact command / [N]o`. `always` appends an exact
39
+ rule to the policy file. `--approve-cmd COMMAND` asks by running your own command with the
40
+ argv as its one argument (exit 0 = yes), for a popup or notification.
41
+ - **Limits:** request size, argument count, output (64 MiB) and a run time (`--timeout`, 300 s).
42
+ The socket is mode 0600 in a 0700 directory; the server refuses a directory that is not yours
43
+ and private. File descriptors sent over the socket are ignored.
44
+
45
+ ## Python
46
+
47
+ from pip_vm_hostrun import run, call, output, Denied, HostrunError
48
+
49
+ run(["podman", "ps"], capture_output=True, text=True, check=True) # like subprocess.run
50
+ call(["sudo", "iw", "phy", "phy1", "set", "netns", "1234"]) # exit status; output passes through
51
+ output(["id", "-u"]) # stdout as text; raises if it fails
52
+
53
+ `Denied` means the host said no. `HostrunError` covers everything else (no server, too long, timed out).
54
+
55
+ ## What this is not
56
+
57
+ It is a narrow, audited doorway, not a sandbox. Whatever you allow runs with your full
58
+ privileges, so allow exact commands, not interpreters or `sh -c`.
59
+
60
+ pip-vm is the QEMU/podman jail runner this was written for. hostrun does not depend on it: any
61
+ jail that shares a directory and sets `HOSTRUN_SOCKET` to the socket inside it will work.
@@ -0,0 +1,11 @@
1
+ """Run commands on the host from inside a jail, through one socket, with a policy and approval.
2
+
3
+ from pip_vm_hostrun import run, call, output
4
+
5
+ run(["podman", "ps"]) # like subprocess.run: locally it just runs
6
+ output(["id", "-u"]) # in a jail (HOSTRUN_SOCKET or PIP_VM_COMM set) it goes to the host
7
+ """
8
+ from .client import call, jailed, output, run
9
+ from .common import Denied, HostrunError
10
+
11
+ __all__ = ["run", "call", "output", "jailed", "Denied", "HostrunError"]
@@ -0,0 +1,60 @@
1
+ import argparse
2
+ import sys
3
+
4
+ from .client import run
5
+ from .common import Denied, HostrunError
6
+ from .server import Server, command_approver, tty_approver
7
+
8
+
9
+ def client_main(argv=None):
10
+ """`hostrun CMD ARGS...`: run it on the host if jailed, else here."""
11
+ argv = list(sys.argv[1:] if argv is None else argv)
12
+ if argv[:1] == ["--"]:
13
+ argv = argv[1:]
14
+ if not argv:
15
+ print("usage: hostrun CMD [ARGS...]", file=sys.stderr)
16
+ return 2
17
+ try:
18
+ return run(argv).returncode
19
+ except Denied as e:
20
+ print(f"hostrun: {e}", file=sys.stderr)
21
+ return 126
22
+ except HostrunError as e:
23
+ print(f"hostrun: {e}", file=sys.stderr)
24
+ return 127
25
+ except FileNotFoundError:
26
+ print(f"hostrun: command not found: {argv[0]}", file=sys.stderr)
27
+ return 127
28
+
29
+
30
+ def server_main(argv=None):
31
+ parser = argparse.ArgumentParser(
32
+ prog="pip-vm-hostrun",
33
+ description="Serve one jail's requests to run commands on this host.")
34
+ sub = parser.add_subparsers(dest="cmd", required=True)
35
+ serve = sub.add_parser("serve", help="listen in the jail's shared directory (pip-vm's, by tool name)")
36
+ serve.add_argument("name", help="the tool or jail name")
37
+ serve.add_argument("--approve-cmd", metavar="COMMAND",
38
+ help="ask by running COMMAND with the exact command line as its argument "
39
+ "(exit 0 = allow) instead of asking on this terminal")
40
+ serve.add_argument("--timeout", type=int, default=300, help="seconds a command may run (default 300)")
41
+ where = sub.add_parser("policy", help="show where a jail's policy file is")
42
+ where.add_argument("name")
43
+ args = parser.parse_args(argv)
44
+ try:
45
+ if args.cmd == "policy":
46
+ print(Server(args.name).policy_file)
47
+ return 0
48
+ approver = command_approver(args.approve_cmd) if args.approve_cmd else tty_approver
49
+ server = Server(args.name, approver=approver, timeout=args.timeout)
50
+ server.bind()
51
+ print(f"hostrun: serving {server.socket_path}\n policy {server.policy_file} "
52
+ f"(commands matching nothing are asked about)", file=sys.stderr)
53
+ try:
54
+ server.serve_forever()
55
+ except KeyboardInterrupt:
56
+ pass
57
+ return 0
58
+ except HostrunError as e:
59
+ print(f"pip-vm-hostrun: {e}", file=sys.stderr)
60
+ return 1
@@ -0,0 +1,91 @@
1
+ """Run a command on the host. Locally that just runs it; in a jail it goes through the socket."""
2
+ import base64
3
+ import json
4
+ import os
5
+ import socket
6
+ import subprocess
7
+ import sys
8
+
9
+ from .common import (CHUNK, ENV_COMM, ENV_SOCKET, SOCKET_NAME, Denied, HostrunError,
10
+ check_argv)
11
+
12
+
13
+ def jailed():
14
+ """True if we are in a jail that points at a hostrun server."""
15
+ return bool(os.environ.get(ENV_SOCKET) or os.environ.get(ENV_COMM))
16
+
17
+
18
+ def socket_path():
19
+ explicit = os.environ.get(ENV_SOCKET)
20
+ if explicit:
21
+ return explicit
22
+ return os.path.join(os.environ[ENV_COMM], SOCKET_NAME)
23
+
24
+
25
+ def run(argv, *, input=None, capture_output=False, text=False, check=False, timeout=None):
26
+ """Like subprocess.run(argv), but on the host if we are jailed. Never uses a shell."""
27
+ argv = [os.fspath(a) for a in check_argv(list(argv))]
28
+ if not jailed():
29
+ return subprocess.run(argv, input=input, capture_output=capture_output,
30
+ text=text, check=check, timeout=timeout)
31
+ if isinstance(input, str):
32
+ input = input.encode()
33
+ out, err, code = _remote(argv, input, capture_output, timeout)
34
+ if text:
35
+ out = out.decode(errors="replace") if out is not None else None
36
+ err = err.decode(errors="replace") if err is not None else None
37
+ done = subprocess.CompletedProcess(argv, code, out, err)
38
+ if check:
39
+ done.check_returncode()
40
+ return done
41
+
42
+
43
+ def call(argv, **kw):
44
+ """Run it, let it print, and return its exit status."""
45
+ return run(argv, **kw).returncode
46
+
47
+
48
+ def output(argv, **kw):
49
+ """Run it and return what it printed, as text. Raises if it fails."""
50
+ return run(argv, capture_output=True, text=True, check=True, **kw).stdout
51
+
52
+
53
+ def _remote(argv, input, capture, timeout):
54
+ path = socket_path()
55
+ conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
56
+ conn.settimeout(timeout)
57
+ try:
58
+ conn.connect(path)
59
+ except OSError as e:
60
+ raise HostrunError(f"cannot reach the host at {path} ({e.strerror}): is "
61
+ f"`pip-vm-hostrun serve NAME` running on the host?") from None
62
+ request = {"v": 1, "argv": argv}
63
+ if input is not None:
64
+ request["input"] = base64.b64encode(input).decode()
65
+ out = bytearray() if capture else None
66
+ err = bytearray() if capture else None
67
+ code = None
68
+ with conn, conn.makefile("rwb") as f:
69
+ f.write(json.dumps(request).encode() + b"\n")
70
+ f.flush()
71
+ for line in f:
72
+ frame = json.loads(line)
73
+ if "out" in frame or "err" in frame:
74
+ stream = "out" if "out" in frame else "err"
75
+ data = base64.b64decode(frame[stream])
76
+ if capture:
77
+ (out if stream == "out" else err).extend(data)
78
+ else:
79
+ target = sys.stdout if stream == "out" else sys.stderr
80
+ target.flush()
81
+ os.write(target.fileno(), data)
82
+ elif "exit" in frame:
83
+ code = frame["exit"]
84
+ break
85
+ elif "denied" in frame:
86
+ raise Denied(frame["denied"])
87
+ elif "error" in frame:
88
+ raise HostrunError(frame["error"])
89
+ if code is None:
90
+ raise HostrunError("the host closed the connection before the command finished")
91
+ return (bytes(out) if capture else None, bytes(err) if capture else None, code)
@@ -0,0 +1,64 @@
1
+ """Names and paths shared by the client and the server."""
2
+ import os
3
+ import re
4
+ from pathlib import Path
5
+
6
+ SOCKET_NAME = "hostrun.sock"
7
+ ENV_SOCKET = "HOSTRUN_SOCKET" # the socket to use, if you are jailed
8
+ ENV_COMM = "PIP_VM_COMM" # set by pip-vm: the jail's shared directory
9
+
10
+ MAX_REQUEST = 1 << 20 # bytes in one request line
11
+ MAX_ARGS = 1000
12
+ MAX_ARGV_BYTES = 128 * 1024
13
+ CHUNK = 64 * 1024
14
+
15
+ NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.+-]*")
16
+
17
+
18
+ class HostrunError(Exception):
19
+ """Something went wrong talking to, or running through, the host."""
20
+
21
+
22
+ class Denied(HostrunError):
23
+ """The host refused to run the command."""
24
+
25
+
26
+ def check_name(name):
27
+ if not NAME.fullmatch(name):
28
+ raise HostrunError(f"invalid name: {name!r}")
29
+ return name
30
+
31
+
32
+ def comm_dir(name):
33
+ """The host side of a jail's shared directory: where pip-vm puts it."""
34
+ runtime = os.environ.get("XDG_RUNTIME_DIR") or f"/run/user/{os.getuid()}"
35
+ return Path(runtime) / "pip-vm" / check_name(name)
36
+
37
+
38
+ def policy_path(name):
39
+ config = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
40
+ return Path(config) / "pip-vm" / "hostrun" / f"{check_name(name)}.policy"
41
+
42
+
43
+ def check_argv(argv):
44
+ """Raise HostrunError unless argv is a sane list of non-empty-first strings."""
45
+ if not isinstance(argv, list) or not argv:
46
+ raise HostrunError("argv must be a non-empty list")
47
+ if len(argv) > MAX_ARGS:
48
+ raise HostrunError("too many arguments")
49
+ total = 0
50
+ for arg in argv:
51
+ if not isinstance(arg, str) or "\0" in arg:
52
+ raise HostrunError("arguments must be strings without NUL")
53
+ total += len(arg.encode("utf-8", "surrogateescape")) + 1
54
+ if not argv[0]:
55
+ raise HostrunError("the command is empty")
56
+ if total > MAX_ARGV_BYTES:
57
+ raise HostrunError("the command line is too long")
58
+ return argv
59
+
60
+
61
+ def display(argv):
62
+ """The exact argv, one shell-quoted word each, with anything unprintable spelled out."""
63
+ import shlex
64
+ return " ".join(shlex.quote(a) if a.isprintable() else ascii(a) for a in argv)
@@ -0,0 +1,63 @@
1
+ """The policy file: which commands a jail may run on the host.
2
+
3
+ One rule per line, first match wins, and a command that matches nothing is asked about:
4
+
5
+ allow podman ps ...
6
+ ask sudo iw phy * set netns *
7
+ deny sudo ...
8
+
9
+ Each word is a glob (fnmatch) for the argv word in that position, so `*` never spans
10
+ words. A final `...` means "and anything after". `allow` must name at least one word.
11
+ """
12
+ import fnmatch
13
+ import glob
14
+ import shlex
15
+ from collections import namedtuple
16
+
17
+ from .common import HostrunError
18
+
19
+ ACTIONS = ("allow", "ask", "deny")
20
+ Rule = namedtuple("Rule", "action patterns rest")
21
+
22
+
23
+ def parse(text):
24
+ rules = []
25
+ for number, line in enumerate(text.splitlines(), 1):
26
+ line = line.strip()
27
+ if not line or line.startswith("#"):
28
+ continue
29
+ try:
30
+ words = shlex.split(line)
31
+ except ValueError as e:
32
+ raise HostrunError(f"policy line {number}: {e}") from None
33
+ action, patterns = words[0], words[1:]
34
+ if action not in ACTIONS:
35
+ raise HostrunError(f"policy line {number}: {action!r} is not allow, ask or deny")
36
+ rest = bool(patterns) and patterns[-1] == "..."
37
+ if rest:
38
+ patterns = patterns[:-1]
39
+ if action == "allow" and not patterns:
40
+ raise HostrunError(f"policy line {number}: allow needs at least one word")
41
+ rules.append(Rule(action, patterns, rest))
42
+ return rules
43
+
44
+
45
+ def matches(rule, argv):
46
+ if rule.rest:
47
+ if len(argv) < len(rule.patterns):
48
+ return False
49
+ elif len(argv) != len(rule.patterns):
50
+ return False
51
+ return all(fnmatch.fnmatchcase(arg, pat) for arg, pat in zip(argv, rule.patterns))
52
+
53
+
54
+ def decide(rules, argv):
55
+ for rule in rules:
56
+ if matches(rule, argv):
57
+ return rule.action
58
+ return "ask"
59
+
60
+
61
+ def exact_rule(argv):
62
+ """An `allow` line matching exactly this argv and nothing else."""
63
+ return "allow " + " ".join(shlex.quote(glob.escape(a)) for a in argv)
@@ -0,0 +1,218 @@
1
+ """The host side: listen on one jail's socket, decide each request, run what is allowed.
2
+
3
+ The socket is the jail's identity: one server per jail, and its policy file is named for
4
+ the jail. Nothing but the argv comes from the jail (no environment, no working directory):
5
+ the command runs with the server's own environment, as you.
6
+ """
7
+ import base64
8
+ import json
9
+ import os
10
+ import shlex
11
+ import socket
12
+ import stat
13
+ import subprocess
14
+ import sys
15
+ import threading
16
+ import time
17
+ from pathlib import Path
18
+
19
+ from . import policy
20
+ from .common import (CHUNK, MAX_REQUEST, SOCKET_NAME, HostrunError, check_argv, comm_dir,
21
+ display, policy_path)
22
+
23
+ MAX_OUTPUT = 64 << 20 # bytes of output per command, then it is killed
24
+
25
+
26
+ def tty_approver(shown, argv):
27
+ """Ask on your terminal. Returns "once", "always" or "no"."""
28
+ with open("/dev/tty", "r+") as tty:
29
+ tty.write(f"\nhostrun: the jail asks to run on the host:\n {shown}\n"
30
+ f"[y]es once / [a]lways this exact command / [N]o: ")
31
+ tty.flush()
32
+ answer = tty.readline().strip().lower()
33
+ return {"y": "once", "yes": "once", "a": "always", "always": "always"}.get(answer, "no")
34
+
35
+
36
+ def command_approver(command):
37
+ """Approve by running your own command with the shown argv as its one argument (exit 0 = yes)."""
38
+ base = shlex.split(command)
39
+
40
+ def approve(shown, argv):
41
+ return "once" if subprocess.run(base + [shown]).returncode == 0 else "no"
42
+ return approve
43
+
44
+
45
+ class Server:
46
+ def __init__(self, name, *, approver=tty_approver, policy_file=None, timeout=300, directory=None):
47
+ self.name = name
48
+ self.directory = Path(directory) if directory else comm_dir(name)
49
+ self.policy_file = Path(policy_file) if policy_file else policy_path(name)
50
+ self.approver = approver
51
+ self.timeout = timeout
52
+ self.sock = None
53
+ self._ask_lock = threading.Lock()
54
+
55
+ @property
56
+ def socket_path(self):
57
+ return self.directory / SOCKET_NAME
58
+
59
+ def _rules(self):
60
+ try:
61
+ return policy.parse(self.policy_file.read_text())
62
+ except FileNotFoundError:
63
+ return []
64
+
65
+ def _remember(self, argv):
66
+ self.policy_file.parent.mkdir(parents=True, exist_ok=True)
67
+ with open(self.policy_file, "a") as f:
68
+ f.write(policy.exact_rule(argv) + "\n")
69
+
70
+ def bind(self):
71
+ self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
72
+ info = self.directory.stat()
73
+ if info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
74
+ raise HostrunError(f"{self.directory} must be yours and private (mode 0700)")
75
+ if self.socket_path.exists() or self.socket_path.is_symlink():
76
+ probe = socket.socket(socket.AF_UNIX)
77
+ try:
78
+ probe.connect(str(self.socket_path))
79
+ except OSError: # nobody is listening: a stale file from a crash
80
+ self.socket_path.unlink()
81
+ else:
82
+ raise HostrunError(f"a server is already running for {self.name}")
83
+ finally:
84
+ probe.close()
85
+ self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
86
+ self.sock.bind(str(self.socket_path))
87
+ self.socket_path.chmod(0o600)
88
+ self.sock.listen(8)
89
+
90
+ def serve_forever(self):
91
+ if self.sock is None:
92
+ self.bind()
93
+ listener = self.sock
94
+ try:
95
+ while True:
96
+ try:
97
+ conn, _ = listener.accept()
98
+ except OSError: # closed from another thread, or a Ctrl-C shutdown
99
+ return
100
+ threading.Thread(target=self.handle, args=(conn,), daemon=True).start()
101
+ finally:
102
+ self.close()
103
+
104
+ def close(self):
105
+ if self.sock:
106
+ self.sock.close()
107
+ self.sock = None
108
+ try:
109
+ self.socket_path.unlink()
110
+ except OSError:
111
+ pass
112
+
113
+ def handle(self, conn):
114
+ send_lock = threading.Lock()
115
+ try:
116
+ with conn, conn.makefile("rwb") as f:
117
+ def send(frame):
118
+ with send_lock:
119
+ f.write(json.dumps(frame).encode() + b"\n")
120
+ f.flush()
121
+ try:
122
+ self._handle(f, send)
123
+ except OSError: # the jail went away mid-request
124
+ pass
125
+ except HostrunError as e:
126
+ self._try(send, {"error": str(e)})
127
+ except Exception as e: # never take the server down for one request
128
+ self._try(send, {"error": f"server error: {type(e).__name__}"})
129
+ except OSError: # ...and closing the connection failed too: nothing to do
130
+ pass
131
+
132
+ @staticmethod
133
+ def _try(send, frame):
134
+ try:
135
+ send(frame)
136
+ except OSError:
137
+ pass
138
+
139
+ def _handle(self, f, send):
140
+ line = f.readline(MAX_REQUEST + 1)
141
+ if len(line) > MAX_REQUEST or not line.endswith(b"\n"):
142
+ raise HostrunError("request too large or incomplete")
143
+ try:
144
+ request = json.loads(line)
145
+ argv = check_argv(request["argv"])
146
+ data = base64.b64decode(request["input"]) if request.get("input") is not None else None
147
+ except (ValueError, KeyError, TypeError):
148
+ raise HostrunError("malformed request") from None
149
+
150
+ shown = display(argv)
151
+ action = policy.decide(self._rules(), argv)
152
+ if action == "ask":
153
+ with self._ask_lock:
154
+ try:
155
+ answer = self.approver(shown, argv)
156
+ except OSError as e:
157
+ raise HostrunError(f"could not ask for approval: {e}") from None
158
+ if answer == "always":
159
+ self._remember(argv)
160
+ action = "allow" if answer in ("once", "always") else "deny"
161
+ if action != "allow":
162
+ send({"denied": f"not allowed on the host: {shown}"})
163
+ return
164
+ self._execute(argv, data, send)
165
+
166
+ def _execute(self, argv, data, send):
167
+ try:
168
+ proc = subprocess.Popen(argv, stdin=subprocess.PIPE if data is not None else subprocess.DEVNULL,
169
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE,
170
+ start_new_session=True)
171
+ except OSError as e:
172
+ send({"error": f"cannot run {argv[0]!r}: {e.strerror}"})
173
+ return
174
+ total = [0]
175
+ killed = threading.Event()
176
+
177
+ def kill():
178
+ killed.set()
179
+ try:
180
+ os.killpg(proc.pid, 9)
181
+ except OSError:
182
+ pass
183
+
184
+ timer = threading.Timer(self.timeout, kill)
185
+ timer.start()
186
+
187
+ def pump(stream, key):
188
+ while chunk := stream.read1(CHUNK):
189
+ total[0] += len(chunk)
190
+ if total[0] > MAX_OUTPUT:
191
+ kill()
192
+ return
193
+ try:
194
+ send({key: base64.b64encode(chunk).decode()})
195
+ except OSError:
196
+ kill()
197
+ return
198
+
199
+ pumps = [threading.Thread(target=pump, args=(proc.stdout, "out")),
200
+ threading.Thread(target=pump, args=(proc.stderr, "err"))]
201
+ for t in pumps:
202
+ t.start()
203
+ if data is not None:
204
+ try:
205
+ proc.stdin.write(data)
206
+ proc.stdin.close()
207
+ except OSError:
208
+ pass
209
+ for t in pumps:
210
+ t.join()
211
+ code = proc.wait()
212
+ timer.cancel()
213
+ proc.stdout.close()
214
+ proc.stderr.close()
215
+ if killed.is_set():
216
+ send({"error": "the command was stopped (timeout, output limit or disconnect)"})
217
+ else:
218
+ send({"exit": code})
@@ -0,0 +1,69 @@
1
+ Metadata-Version: 2.4
2
+ Name: pip-vm-hostrun
3
+ Version: 0.1.0
4
+ Summary: Run commands on the host from inside a jail (a VM or container), through one unix socket, with a policy and your approval
5
+ Author: readwithai
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+
9
+ # pip-vm-hostrun
10
+ Run commands **on the host** from inside a jail (a VM or a container), from Python or the command line. Outside a jail it just runs the command. Sudo-like rules, kept on the host, define which commands are allowed.
11
+
12
+ Designed for use with pip-vm, but any jail runner can use it.
13
+
14
+ Communication is done through one unix socket, with a policy file and your approval. Standard library only.
15
+
16
+ Outside a jail, `hostrun ls` just runs `ls`. Inside one, the same call goes to a server on
17
+ the host, which decides whether to run it. So a tool can be written once and work both ways.
18
+
19
+ # in the jail (a tool, or the shell)
20
+ hostrun podman ps
21
+ python -c "from pip_vm_hostrun import output; print(output(['id', '-u']))"
22
+
23
+ # on the host
24
+ pip-vm-hostrun serve TOOL
25
+
26
+ ## How it works
27
+
28
+ - **The socket is the identity.** `pip-vm-hostrun serve TOOL` listens on
29
+ `$XDG_RUNTIME_DIR/pip-vm/TOOL/hostrun.sock`, the tool's pip-vm communication directory, which is
30
+ the only thing shared with that jail (mounted at `/run/pip-vm`, with `PIP_VM_COMM=/run/pip-vm`).
31
+ One server per jail; its policy is `~/.config/pip-vm/hostrun/TOOL.policy`.
32
+ The jail is "jailed" when `PIP_VM_COMM` or `HOSTRUN_SOCKET` is set. If it is jailed and there is no
33
+ server, you get an error, never a silent local run.
34
+ - **Only an argv crosses.** A list of strings: no shell, no environment, no working directory.
35
+ The command runs as you, with the server's environment. Output and the exit status stream back.
36
+ - **A policy decides**, first match wins, and a command that matches nothing is *asked about*:
37
+
38
+ allow podman ps ...
39
+ ask sudo iw phy * set netns *
40
+ deny sudo ...
41
+
42
+ Each word is an fnmatch glob for the argv word in that position (`*` never spans words), and a
43
+ final `...` means "and anything after". `allow` needs at least one word, so it cannot be written
44
+ as allow-everything by accident.
45
+ - **Asking** shows the exact argv, shell-quoted (unprintable characters spelled out), on the
46
+ server's terminal: `[y]es once / [a]lways this exact command / [N]o`. `always` appends an exact
47
+ rule to the policy file. `--approve-cmd COMMAND` asks by running your own command with the
48
+ argv as its one argument (exit 0 = yes), for a popup or notification.
49
+ - **Limits:** request size, argument count, output (64 MiB) and a run time (`--timeout`, 300 s).
50
+ The socket is mode 0600 in a 0700 directory; the server refuses a directory that is not yours
51
+ and private. File descriptors sent over the socket are ignored.
52
+
53
+ ## Python
54
+
55
+ from pip_vm_hostrun import run, call, output, Denied, HostrunError
56
+
57
+ run(["podman", "ps"], capture_output=True, text=True, check=True) # like subprocess.run
58
+ call(["sudo", "iw", "phy", "phy1", "set", "netns", "1234"]) # exit status; output passes through
59
+ output(["id", "-u"]) # stdout as text; raises if it fails
60
+
61
+ `Denied` means the host said no. `HostrunError` covers everything else (no server, too long, timed out).
62
+
63
+ ## What this is not
64
+
65
+ It is a narrow, audited doorway, not a sandbox. Whatever you allow runs with your full
66
+ privileges, so allow exact commands, not interpreters or `sh -c`.
67
+
68
+ pip-vm is the QEMU/podman jail runner this was written for. hostrun does not depend on it: any
69
+ jail that shares a directory and sets `HOSTRUN_SOCKET` to the socket inside it will work.
@@ -0,0 +1,14 @@
1
+ README.md
2
+ pyproject.toml
3
+ pip_vm_hostrun/__init__.py
4
+ pip_vm_hostrun/cli.py
5
+ pip_vm_hostrun/client.py
6
+ pip_vm_hostrun/common.py
7
+ pip_vm_hostrun/policy.py
8
+ pip_vm_hostrun/server.py
9
+ pip_vm_hostrun.egg-info/PKG-INFO
10
+ pip_vm_hostrun.egg-info/SOURCES.txt
11
+ pip_vm_hostrun.egg-info/dependency_links.txt
12
+ pip_vm_hostrun.egg-info/entry_points.txt
13
+ pip_vm_hostrun.egg-info/top_level.txt
14
+ tests/test_hostrun.py
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ hostrun = pip_vm_hostrun.cli:client_main
3
+ pip-vm-hostrun = pip_vm_hostrun.cli:server_main
@@ -0,0 +1 @@
1
+ pip_vm_hostrun
@@ -0,0 +1,21 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "pip-vm-hostrun"
7
+ version = "0.1.0"
8
+ description = "Run commands on the host from inside a jail (a VM or container), through one unix socket, with a policy and your approval"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ dependencies = []
12
+
13
+ [[project.authors]]
14
+ name = "readwithai"
15
+
16
+ [project.scripts]
17
+ hostrun = "pip_vm_hostrun.cli:client_main"
18
+ pip-vm-hostrun = "pip_vm_hostrun.cli:server_main"
19
+
20
+ [tool.setuptools]
21
+ packages = ["pip_vm_hostrun"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,242 @@
1
+ import os
2
+ import shutil
3
+ import stat
4
+ import subprocess
5
+ import sys
6
+ import tempfile
7
+ import threading
8
+ import unittest
9
+ from pathlib import Path
10
+ from unittest.mock import patch
11
+
12
+ from pip_vm_hostrun import Denied, HostrunError, call, jailed, output, run
13
+ from pip_vm_hostrun import policy
14
+ from pip_vm_hostrun.common import check_argv, display
15
+ from pip_vm_hostrun.server import Server
16
+
17
+
18
+ class PolicyTests(unittest.TestCase):
19
+ def test_first_match_wins_and_default_is_ask(self):
20
+ rules = policy.parse("""
21
+ # comment
22
+ deny sudo ...
23
+ allow podman ps ...
24
+ ask iw phy * set netns *
25
+ """)
26
+ self.assertEqual(policy.decide(rules, ["sudo", "ls"]), "deny")
27
+ self.assertEqual(policy.decide(rules, ["podman", "ps", "-a"]), "allow")
28
+ self.assertEqual(policy.decide(rules, ["podman", "ps"]), "allow")
29
+ self.assertEqual(policy.decide(rules, ["podman", "rm"]), "ask")
30
+ self.assertEqual(policy.decide(rules, ["iw", "phy", "phy1", "set", "netns", "12"]), "ask")
31
+ self.assertEqual(policy.decide([], ["anything"]), "ask")
32
+
33
+ def test_globs_do_not_span_words_and_lengths_must_match(self):
34
+ rules = policy.parse("allow echo *")
35
+ self.assertEqual(policy.decide(rules, ["echo", "a"]), "allow")
36
+ self.assertEqual(policy.decide(rules, ["echo", "a", "b"]), "ask") # no `...`
37
+ self.assertEqual(policy.decide(rules, ["echo"]), "ask")
38
+
39
+ def test_allow_everything_is_not_expressible_by_accident(self):
40
+ with self.assertRaises(HostrunError):
41
+ policy.parse("allow ...")
42
+ with self.assertRaises(HostrunError):
43
+ policy.parse("allow")
44
+ with self.assertRaises(HostrunError):
45
+ policy.parse("permit ls")
46
+
47
+ def test_exact_rule_matches_only_that_argv(self):
48
+ argv = ["echo", "a*b", "it's [x]"]
49
+ rules = policy.parse(policy.exact_rule(argv))
50
+ self.assertEqual(policy.decide(rules, argv), "allow")
51
+ self.assertEqual(policy.decide(rules, ["echo", "aXb", "it's [x]"]), "ask")
52
+
53
+
54
+ class ValidationTests(unittest.TestCase):
55
+ def test_bad_argv_is_refused(self):
56
+ for bad in ([], "ls", [""], ["ls", 1], ["a\0b"], ["x"] * 1001, ["x" * 200000]):
57
+ with self.assertRaises(HostrunError):
58
+ check_argv(bad)
59
+
60
+ def test_display_spells_out_unprintable(self):
61
+ self.assertEqual(display(["echo", "a b"]), "echo 'a b'")
62
+ self.assertIn("\\n", display(["echo", "a\nb"]))
63
+
64
+
65
+ class LocalTests(unittest.TestCase):
66
+ def test_not_jailed_just_runs_here(self):
67
+ with patch.dict(os.environ, {}, clear=False):
68
+ os.environ.pop("HOSTRUN_SOCKET", None)
69
+ os.environ.pop("PIP_VM_COMM", None)
70
+ self.assertFalse(jailed())
71
+ self.assertEqual(output(["echo", "hi"]), "hi\n")
72
+ self.assertEqual(call(["sh", "-c", "exit 3"]), 3)
73
+
74
+
75
+ class Roundtrip(unittest.TestCase):
76
+ """A real server on a real unix socket, with a scripted approver."""
77
+
78
+ def setUp(self):
79
+ self.tmp = Path(tempfile.mkdtemp(prefix="hr"))
80
+ self.addCleanup(shutil.rmtree, self.tmp, True)
81
+ self.asked = []
82
+ self.answer = "no"
83
+ self.server = Server("t", approver=self.approve, policy_file=self.tmp / "t.policy",
84
+ directory=self.tmp / "d", timeout=5)
85
+ self.server.bind()
86
+ threading.Thread(target=self.server.serve_forever, daemon=True).start()
87
+ env = patch.dict(os.environ, {"HOSTRUN_SOCKET": str(self.server.socket_path)})
88
+ env.start()
89
+ self.addCleanup(env.stop)
90
+ self.addCleanup(self.server.close)
91
+
92
+ def approve(self, shown, argv):
93
+ self.asked.append(argv)
94
+ return self.answer
95
+
96
+ def policy(self, text):
97
+ (self.tmp / "t.policy").write_text(text)
98
+
99
+ def test_socket_and_dir_are_private(self):
100
+ self.assertEqual(stat.S_IMODE(self.server.socket_path.stat().st_mode), 0o600)
101
+ self.assertEqual(stat.S_IMODE(self.server.directory.stat().st_mode), 0o700)
102
+
103
+ def test_allowed_command_runs_and_streams_output_and_exit(self):
104
+ self.policy("allow sh -c ...\n")
105
+ self.assertTrue(jailed())
106
+ done = run(["sh", "-c", "echo out; echo err >&2; exit 4"], capture_output=True, text=True)
107
+ self.assertEqual((done.stdout, done.stderr, done.returncode), ("out\n", "err\n", 4))
108
+ self.assertEqual(self.asked, []) # allowed by policy: nobody was asked
109
+
110
+ def test_stdin_and_binary_output(self):
111
+ self.policy("allow cat\nallow printf ...\n")
112
+ self.assertEqual(run(["cat"], input="hello", capture_output=True, text=True).stdout, "hello")
113
+ done = run(["printf", r"\000\377"], capture_output=True)
114
+ self.assertEqual(done.stdout, b"\x00\xff")
115
+
116
+ def test_unmatched_is_asked_and_no_means_denied(self):
117
+ self.answer = "no"
118
+ with self.assertRaises(Denied):
119
+ run(["echo", "hi"], capture_output=True)
120
+ self.assertEqual(self.asked, [["echo", "hi"]])
121
+
122
+ def test_yes_once_runs_but_does_not_remember(self):
123
+ self.answer = "once"
124
+ self.assertEqual(output(["echo", "hi"]), "hi\n")
125
+ output(["echo", "hi"])
126
+ self.assertEqual(len(self.asked), 2)
127
+
128
+ def test_always_remembers_only_that_exact_command(self):
129
+ self.answer = "always"
130
+ output(["echo", "hi"])
131
+ self.answer = "no"
132
+ self.assertEqual(output(["echo", "hi"]), "hi\n") # remembered: not asked again
133
+ with self.assertRaises(Denied):
134
+ output(["echo", "other"]) # a different argv is
135
+ self.assertEqual(len(self.asked), 2)
136
+
137
+ def test_deny_rule_beats_everything_and_never_asks(self):
138
+ self.policy("deny rm ...\n")
139
+ self.answer = "once"
140
+ with self.assertRaises(Denied):
141
+ run(["rm", "-rf", "/nonexistent"])
142
+ self.assertEqual(self.asked, [])
143
+
144
+ def test_no_shell_so_metacharacters_are_just_text(self):
145
+ self.policy("allow echo ...\n")
146
+ self.assertEqual(output(["echo", "a; touch /tmp/should-not-exist-hostrun"]),
147
+ "a; touch /tmp/should-not-exist-hostrun\n")
148
+ self.assertFalse(os.path.exists("/tmp/should-not-exist-hostrun"))
149
+
150
+ def test_only_the_argv_is_sent_never_environment_or_cwd(self):
151
+ import json
152
+ import socket
153
+ path = self.tmp / "fake.sock"
154
+ fake = socket.socket(socket.AF_UNIX)
155
+ fake.bind(str(path))
156
+ fake.listen(1)
157
+ got = []
158
+
159
+ def serve():
160
+ conn, _ = fake.accept()
161
+ with conn, conn.makefile("rwb") as f:
162
+ got.append(json.loads(f.readline()))
163
+ f.write(b'{"exit": 0}\n')
164
+ f.flush()
165
+ thread = threading.Thread(target=serve)
166
+ thread.start()
167
+ with patch.dict(os.environ, {"HOSTRUN_SOCKET": str(path), "SECRET_FROM_JAIL": "x"}):
168
+ run(["echo", "hi"], capture_output=True)
169
+ thread.join()
170
+ fake.close()
171
+ self.assertEqual(got, [{"v": 1, "argv": ["echo", "hi"]}])
172
+
173
+ def test_server_does_not_pass_a_jail_chosen_environment_to_popen(self):
174
+ self.policy("allow true\n")
175
+ real = subprocess.Popen
176
+ seen = {}
177
+
178
+ def spy(argv, **kw):
179
+ seen.update(kw)
180
+ return real(argv, **kw)
181
+ with patch("pip_vm_hostrun.server.subprocess.Popen", spy):
182
+ call(["true"])
183
+ self.assertNotIn("env", seen)
184
+ self.assertNotIn("cwd", seen)
185
+
186
+ def test_missing_command_is_an_error_not_a_crash(self):
187
+ self.policy("allow no-such-command-hostrun ...\nallow true\n")
188
+ with self.assertRaises(HostrunError):
189
+ run(["no-such-command-hostrun"])
190
+ self.assertEqual(call(["true"]), 0)
191
+
192
+ def test_malformed_request_gets_an_error_and_server_survives(self):
193
+ import socket
194
+ s = socket.socket(socket.AF_UNIX)
195
+ s.connect(str(self.server.socket_path))
196
+ s.sendall(b"not json\n")
197
+ self.assertIn(b"error", s.recv(1000))
198
+ s.close()
199
+ self.policy("allow true\n")
200
+ self.assertEqual(call(["true"]), 0)
201
+
202
+ def test_timeout_kills_the_command(self):
203
+ self.policy("allow sleep ...\n")
204
+ self.server.timeout = 0.3
205
+ with self.assertRaises(HostrunError):
206
+ run(["sleep", "5"])
207
+
208
+ def test_one_server_per_jail(self):
209
+ other = Server("t", directory=self.server.directory)
210
+ with self.assertRaises(HostrunError):
211
+ other.bind()
212
+
213
+ def test_stale_socket_is_replaced(self):
214
+ self.server.close()
215
+ d = self.tmp / "d2"
216
+ d.mkdir(mode=0o700)
217
+ (d / "hostrun.sock").write_text("stale")
218
+ s = Server("t2", directory=d)
219
+ s.bind()
220
+ self.addCleanup(s.close)
221
+ self.assertTrue(stat.S_ISSOCK((d / "hostrun.sock").stat().st_mode))
222
+
223
+ def test_group_accessible_directory_is_refused(self):
224
+ d = self.tmp / "open"
225
+ d.mkdir()
226
+ d.chmod(0o755)
227
+ with self.assertRaises(HostrunError):
228
+ Server("t3", directory=d).bind()
229
+
230
+
231
+ class JailedWithoutServer(unittest.TestCase):
232
+ def test_comm_set_but_no_server_is_an_error_not_a_local_run(self):
233
+ d = tempfile.mkdtemp()
234
+ self.addCleanup(shutil.rmtree, d, True)
235
+ with patch.dict(os.environ, {"PIP_VM_COMM": d}):
236
+ os.environ.pop("HOSTRUN_SOCKET", None)
237
+ with self.assertRaises(HostrunError):
238
+ run(["echo", "would have run in the jail"])
239
+
240
+
241
+ if __name__ == "__main__":
242
+ unittest.main()