empeira 0.1.0.pre.alpha.1

data/resources/nodes/managed_file.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'pathname'
+require 'tempfile'
+require 'fileutils'
+
+module Empeira
+  # Runs inside the owned guest using its agent Ruby; no separate guest inventory.
+  class ManagedFile
+    def initialize(request)
+      @path = Pathname(request.fetch('path'))
+      @content = request['content']
+      @accepted = request.fetch('accepted')
+      @mode = request.fetch('mode')
+    end
+
+    # rubocop:disable-next Naming/PredicateMethod -- Reconciliation mutates the managed file.
+    def reconcile
+      verify_parents!
+      current = verify_file!
+      return false if current.nil? && @content.nil?
+      return false if current && current == @content && (@path.stat.mode & 0o7777) == @mode
+
+      if @content.nil?
+        @path.unlink
+      else
+        write
+      end
+      true
+    end
+
+    private
+
+    def verify_parents!
+      @path.parent.ascend do |parent|
+        next unless parent.exist? || parent.symlink?
+        next if !parent.symlink? && parent.directory?
+
+        raise 'Managed file parent must be a directory, not a symlink'
+      end
+    end
+
+    def verify_file!
+      stat = @path.lstat
+      @content ? current_for_write(stat) : current_for_removal(stat)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def current_for_write(stat)
+      raise 'Command-mock target must be a file or symlink' unless stat.file? || stat.symlink?
+
+      return nil if stat.symlink? || stat.size != @content.bytesize
+
+      @path.binread
+    end
+
+    def current_for_removal(stat)
+      unless stat.file? && stat.nlink == 1 && stat.uid == Process.euid
+        raise 'Refusing to remove an unowned or modified command-mock target'
+      end
+
+      content = @path.binread
+      raise 'Refusing to remove an unowned or modified command-mock target' unless @accepted.include?(content)
+
+      content
+    end
+
+    def write
+      FileUtils.mkdir_p(@path.parent, mode: 0o755)
+      Tempfile.create('.empeira-', @path.parent) do |file|
+        file.chmod(@mode)
+        file.write(@content)
+        file.flush
+        file.fsync
+        File.rename(file.path, @path)
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    changed = Empeira::ManagedFile.new(JSON.parse(ARGV.fetch(0))).reconcile
+    puts JSON.generate('changed' => changed)
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end

data/resources/nodes/management/guest_agent.py

@@ -0,0 +1,415 @@
+#!/usr/bin/python3
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Private VirtIO-Serial execution adapter; no account authentication or network."""
+import base64
+import hashlib
+import json
+import os
+import select
+import signal
+import shutil
+import subprocess
+import sys
+import stat
+import tempfile
+import time
+import errno
+import fcntl
+import pty
+import pwd
+import struct
+import termios
+
+LIMIT = 131072
+CHUNK = 16384
+TOKEN = sys.argv[2]
+PORT = sys.argv[1]
+ROOT = '/run/empeira-management'
+os.umask(0o077)
+os.makedirs(ROOT, mode=0o700, exist_ok=True)
+metadata = os.lstat(ROOT)
+if not stat.S_ISDIR(metadata.st_mode) or metadata.st_uid != 0 or metadata.st_mode & 0o077:
+    raise RuntimeError('Management staging ownership is invalid')
+if os.geteuid() != 0:
+    raise RuntimeError('Management requires numeric UID 0')
+
+
+def interrupted(signum, _frame):
+    raise SystemExit(128 + signum)
+
+
+for termination_signal in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+    signal.signal(termination_signal, interrupted)
+
+
+def supervise(ports):
+    # Independent bounded workers preserve the existing streaming/atomic-upload protocol.
+    # A blocked or failed session cannot stall another channel or ordinary Puppet execution.
+    workers = {}
+    try:
+        while True:
+            for port in ports:
+                worker = workers.get(port)
+                if worker is None or worker.poll() is not None:
+                    workers[port] = subprocess.Popen([sys.executable, __file__, port, TOKEN])
+            time.sleep(0.5)
+    finally:
+        for worker in workers.values():
+            if worker.poll() is None:
+                worker.terminate()
+        for worker in workers.values():
+            try:
+                worker.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                worker.kill()
+                worker.wait()
+
+
+if len(sys.argv) > 3:
+    supervise([PORT, *sys.argv[3:]])
+    raise SystemExit(0)
+
+fd = os.open(PORT, os.O_RDWR | os.O_NONBLOCK)
+events = select.epoll()
+events.register(fd, select.EPOLLIN | select.EPOLLET | select.EPOLLHUP)
+buffer = bytearray()
+active = None
+request_id = None
+
+
+def send(data):
+    data['id'] = request_id
+    raw = (json.dumps(data, separators=(',', ':')) + '\n').encode()
+    if len(raw) > LIMIT:
+        raise ValueError('Oversized protocol frame')
+    deadline = time.monotonic() + 5
+    while raw:
+        if time.monotonic() >= deadline:
+            raise TimeoutError()
+        try:
+            written = os.write(fd, raw)
+            if written <= 0:
+                raise EOFError()
+            raw = raw[written:]
+        except BlockingIOError:
+            select.select([], [fd], [], 2)
+
+
+def session_groups(pid):
+    groups = set()
+    for entry in os.scandir('/proc'):
+        if not entry.name.isdigit():
+            continue
+        try:
+            with open(entry.path + '/stat') as source:
+                fields = source.read().rpartition(') ')[2].split()
+            if fields[0] != 'Z' and int(fields[3]) == pid:
+                groups.add(int(fields[2]))
+        except (FileNotFoundError, ProcessLookupError):
+            continue
+    return groups
+
+
+def terminate_groups(pid):
+    # The unreaped session leader pins the identity even when its shell created job-control groups.
+    groups = session_groups(pid)
+    if not groups:
+        return
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        for group in groups:
+            try:
+                os.killpg(group, sig)
+            except ProcessLookupError:
+                pass
+        if sig == signal.SIGTERM:
+            time.sleep(0.1)
+            groups = session_groups(pid)
+
+
+def terminate():
+    global active
+    if not active:
+        return
+    if active['kind'] in ('exec', 'shell'):
+        process = active['process']
+        # The unreaped session leader pins the PID/process-group until cleanup.
+        terminate_groups(process.pid)
+        process.wait()
+        for pipe in active['pipes']:
+            if isinstance(pipe, int) and pipe not in active['open']:
+                continue
+            if not isinstance(pipe, int) and pipe.closed:
+                continue
+            try:
+                events.unregister(pipe if isinstance(pipe, int) else pipe.fileno())
+            except (FileNotFoundError, OSError):
+                pass
+            os.close(pipe) if isinstance(pipe, int) else pipe.close()
+    else:
+        active['file'].close()
+        os.unlink(active['path'])
+    active = None
+
+
+def start_exec(message):
+    global active
+    argv = message['argv']
+    if not isinstance(argv, list) or not argv or not all(isinstance(s, str) and '\0' not in s for s in argv):
+        raise ValueError('Invalid command arguments')
+    try:
+        process = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                                   stderr=subprocess.PIPE, start_new_session=True,
+                                   env={**{key: value for key, value in os.environ.items() if key != 'RUNTIME_DIRECTORY'}, 'PATH': '/opt/puppetlabs/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'})
+    except OSError as error:
+        send({'type': 'stderr', 'data': base64.b64encode((os.strerror(error.errno) + '\n').encode()).decode()})
+        send({'type': 'exit', 'status': 127 if error.errno == 2 else 126, 'timed_out': False})
+        return
+    pipes = {process.stdout.fileno(): (process.stdout, 'stdout'),
+             process.stderr.fileno(): (process.stderr, 'stderr')}
+    active = {'kind': 'exec', 'process': process, 'pipes': [process.stdout, process.stderr],
+              'open': pipes, 'deadline': time.monotonic() + message['timeout'] if message['timeout'] else None}
+    for pipe in pipes:
+        os.set_blocking(pipe, False)
+        events.register(pipe, select.EPOLLIN | select.EPOLLHUP)
+    send({'type': 'started'})
+
+
+class ShellProcess:
+    def __init__(self, pid):
+        self.pid = pid
+
+    def wait(self):
+        _, status = os.waitpid(self.pid, 0)
+        return os.WEXITSTATUS(status) if os.WIFEXITED(status) else -os.WTERMSIG(status)
+
+
+def terminal_size(message):
+    size = message.get('size')
+    if (not isinstance(size, list) or len(size) != 2 or
+            not all(type(value) is int and 0 < value <= 65535 for value in size)):
+        raise ValueError('Invalid terminal dimensions')
+    return struct.pack('HHHH', *size, 0, 0)
+
+
+def command_environment():
+    return {**{key: value for key, value in os.environ.items() if key != 'RUNTIME_DIRECTORY'},
+            'PATH': '/opt/puppetlabs/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'}
+
+
+SHELL_RC = '/usr/local/libexec/empeira-management-shell-rc'
+
+
+def start_shell(message):
+    global active
+    size = terminal_size(message)
+    term = message.get('term', 'xterm')
+    if not isinstance(term, str) or not 1 <= len(term) <= 64 or not all(c.isalnum() or c in '-_.+' for c in term):
+        raise ValueError('Invalid terminal type')
+    shell = shutil.which('bash') or shutil.which('sh')
+    if not shell:
+        raise ValueError('No guest shell is available')
+    pid, master = pty.fork()
+    if pid == 0:
+        try:
+            fcntl.ioctl(0, termios.TIOCSWINSZ, size)
+            try:
+                home = pwd.getpwuid(0).pw_dir
+            except KeyError:
+                home = '/'
+            os.chdir(home if os.path.isdir(home) else '/')
+            arguments = [shell, '--rcfile', SHELL_RC, '-i'] if os.path.basename(shell) == 'bash' else [shell, '-i']
+            os.execvpe(shell, arguments, {**command_environment(), 'HOME': home, 'HISTFILE': '/dev/null',
+                                        'USER': 'root', 'LOGNAME': 'root', 'TERM': term})
+        except Exception:
+            os._exit(126)
+    os.set_blocking(master, False)
+    active = {'kind': 'shell', 'process': ShellProcess(pid), 'pipes': [master],
+              'open': {master: (master, 'stdout')}, 'deadline': None,
+              'input': bytearray(), 'master': master}
+    events.register(master, select.EPOLLIN | select.EPOLLHUP)
+    send({'type': 'started'})
+    send({'type': 'ready'})
+
+
+def shell_input(message):
+    data = base64.b64decode(message['data'], validate=True)
+    if len(data) > CHUNK or active['input']:
+        raise ValueError('Shell input exceeds its granted credit')
+    active['input'].extend(data)
+    events.modify(active['master'], select.EPOLLIN | select.EPOLLOUT | select.EPOLLHUP)
+
+
+def flush_shell_input():
+    master = active['master']
+    try:
+        written = os.write(master, active['input'])
+        del active['input'][:written]
+    except BlockingIOError:
+        return
+    if not active['input']:
+        events.modify(master, select.EPOLLIN | select.EPOLLHUP)
+        send({'type': 'ready'})
+
+
+def handle(message):
+    global active, request_id
+    kind = message['type']
+    if kind == 'hello':
+        if message.get('token') != TOKEN:
+            raise ValueError('Instance identity mismatch')
+        if active:
+            terminate()
+        request_id = message['id']
+        send({'type': 'hello', 'token': TOKEN, 'version': 2})
+        return
+    if message['id'] != request_id:
+        raise ValueError('Request identity mismatch')
+    if kind == 'cancel':
+        terminate()
+        send({'type': 'exit', 'status': 130, 'timed_out': False})
+    elif kind == 'exec' and active is None:
+        timeout = message['timeout']
+        if timeout is not None and (type(timeout) not in (int, float) or not 0 < timeout <= 86400):
+            raise ValueError('Invalid operation timeout')
+        start_exec(message)
+    elif kind == 'shell' and active is None:
+        start_shell(message)
+    elif active and active['kind'] == 'shell' and kind == 'input':
+        shell_input(message)
+    elif active and active['kind'] == 'shell' and kind == 'resize':
+        fcntl.ioctl(active['master'], termios.TIOCSWINSZ, terminal_size(message))
+    elif active and active['kind'] == 'shell' and kind == 'eof':
+        terminate()
+        send({'type': 'exit', 'status': 0, 'timed_out': False})
+    elif active and active['kind'] == 'shell' and kind == 'signal':
+        allowed = {'INT': signal.SIGINT, 'TERM': signal.SIGTERM, 'HUP': signal.SIGHUP,
+                   'TSTP': signal.SIGTSTP, 'CONT': signal.SIGCONT}
+        sig = allowed.get(message.get('signal'))
+        group = os.tcgetpgrp(active['master'])
+        if sig is None or os.getsid(group) != active['process'].pid:
+            raise ValueError('Invalid shell foreground signal')
+        os.killpg(group, sig)
+    elif kind == 'upload' and active is None:
+        file = tempfile.NamedTemporaryFile(dir=ROOT, delete=False)
+        active = {'kind': 'upload', 'file': file, 'path': file.name, 'digest': hashlib.sha256(),
+                  'deadline': time.monotonic() + 120}
+        send({'type': 'ready'})
+    elif kind == 'chunk' and active and active['kind'] == 'upload':
+        data = base64.b64decode(message['data'], validate=True)
+        if len(data) > CHUNK:
+            raise ValueError('Oversized upload chunk')
+        active['file'].write(data)
+        active['digest'].update(data)
+        active['deadline'] = time.monotonic() + 120
+        send({'type': 'ready'})
+    elif kind == 'install' and active and active['kind'] == 'upload':
+        destination, mode = message['destination'], message['mode']
+        if not isinstance(destination, str) or not destination.startswith('/') or '\0' in destination:
+            raise ValueError('Invalid destination')
+        if not isinstance(mode, str) or len(mode) != 4 or any(c not in '01234567' for c in mode):
+            raise ValueError('Invalid mode')
+        if active['digest'].hexdigest() != message['sha256']:
+            raise ValueError('Upload integrity mismatch')
+        active['file'].flush()
+        os.fsync(active['file'].fileno())
+        staged = active['path']
+        active['file'].close()
+        active = None
+        pending = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=os.path.dirname(destination), delete=False) as target:
+                pending = target.name
+                with open(staged, 'rb') as source:
+                    shutil.copyfileobj(source, target, CHUNK)
+                target.flush()
+                os.fchmod(target.fileno(), int(mode, 8))
+                os.fsync(target.fileno())
+            os.replace(pending, destination)
+            pending = None
+            send({'type': 'exit', 'status': 0, 'timed_out': False})
+        except OSError as error:
+            send({'type': 'stderr', 'data': base64.b64encode((os.strerror(error.errno) + '\n').encode()).decode()})
+            send({'type': 'exit', 'status': 1, 'timed_out': False})
+        finally:
+            os.unlink(staged)
+            if pending:
+                os.unlink(pending)
+    else:
+        raise ValueError('Unexpected protocol operation')
+
+
+def serial_input():
+    global buffer, request_id
+    while True:
+        try:
+            data = os.read(fd, CHUNK)
+        except BlockingIOError:
+            return
+        if not data:
+            terminate()
+            buffer.clear()
+            request_id = None
+            return
+        buffer.extend(data)
+        if len(buffer) > LIMIT:
+            raise ValueError('Oversized input frame')
+        while b'\n' in buffer:
+            line, _, remaining = buffer.partition(b'\n')
+            buffer = bytearray(remaining)
+            handle(json.loads(line))
+
+
+def output(pipe):
+    stream, kind = active['open'][pipe]
+    try:
+        data = os.read(pipe, CHUNK)
+    except BlockingIOError:
+        return
+    except OSError as error:
+        if error.errno != errno.EIO or active['kind'] != 'shell':
+            raise
+        data = b''
+    if data:
+        send({'type': kind, 'data': base64.b64encode(data).decode()})
+    else:
+        events.unregister(pipe)
+        del active['open'][pipe]
+        os.close(stream) if isinstance(stream, int) else stream.close()
+
+
+try:
+    while True:
+        timeout = -1 if not active else 0.1
+        for device, flags in events.poll(timeout):
+            if device == fd:
+                serial_input()
+            elif active and active['kind'] in ('exec', 'shell') and device in active['open']:
+                if flags & (select.EPOLLIN | select.EPOLLHUP):
+                    output(device)
+                if active and active['kind'] == 'shell' and flags & select.EPOLLOUT and device in active['open']:
+                    flush_shell_input()
+        if active and active['deadline'] is not None and time.monotonic() >= active['deadline']:
+            terminate()
+            send({'type': 'exit', 'status': None, 'timed_out': True})
+        elif (active and active['kind'] in ('exec', 'shell') and
+              os.waitid(os.P_PID, active['process'].pid, os.WEXITED | os.WNOHANG | os.WNOWAIT)):
+            # wait() reaps only after every output pipe reaches EOF; no PID reuse while cancelling.
+            terminate_groups(active['process'].pid)
+            if active['open']:
+                continue
+            status = active['process'].wait()
+            active = None
+            send({'type': 'exit', 'status': status if status >= 0 else 128 - status, 'timed_out': False})
+except (BrokenPipeError, EOFError, OSError) as error:
+    terminate()
+    print('Management transport failure: ' + type(error).__name__, file=sys.stderr)
+    raise SystemExit(1)
+except Exception as error:
+    terminate()
+    # Never log command arguments, input frames, keys or uploaded content.
+    print('Management protocol failure: ' + type(error).__name__, file=sys.stderr)
+    raise SystemExit(1)
+finally:
+    terminate()
+    events.close()
+    os.close(fd)

data/resources/nodes/management/setup.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Seed management and the ordinary SSH account once, before project bootstrap.
+set -eu
+fail() { echo "VM management setup failed: $1; inspect node shell and serial logs" >&2; exit 1; }
+interpreter=
+for candidate in /usr/bin/python3 /usr/libexec/platform-python; do
+  if test -x "$candidate" && "$candidate" -c 'import sys; sys.exit(sys.version_info < (3, 5))'; then
+    interpreter="$candidate"
+    break
+  fi
+done
+test -n "$interpreter" || fail 'the selected cloud image requires Python 3 before bootstrap'
+test ! -e /usr/local/libexec/empeira-management-python && test ! -L /usr/local/libexec/empeira-management-python || fail 'preexisting management interpreter'
+ln -s "$interpreter" /usr/local/libexec/empeira-management-python
+@SYSTEM_SETUP@
+if test -e /sys/fs/selinux/enforce; then
+  restorecon -R /usr/local/libexec/empeira-management-agent /etc/empeira/management /var/lib/empeira
+fi
+systemctl daemon-reload
+systemctl enable --now empeira-management.service

data/resources/nodes/management/shell_rc.sh

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Preserve interactive configuration and completion without persistent diagnostics history.
+if [ -r /etc/bash.bashrc ]; then
+  . /etc/bash.bashrc
+elif [ -r /etc/bashrc ]; then
+  . /etc/bashrc
+fi
+if [ -r "$HOME/.bashrc" ]; then
+  . "$HOME/.bashrc"
+fi
+HISTFILE=/dev/null
+readonly HISTFILE

data/resources/nodes/management/system_account.sh

@@ -0,0 +1,24 @@
+# Verify regular system SSH account metadata without exposing shadow contents or assigning a fixed UID/GID.
+verify_account() {
+  empeira_account=$(getent passwd empeira) || fail 'missing system SSH account empeira'
+  empeira_uid=$(printf '%s\n' "$empeira_account" | cut -d : -f 3)
+  empeira_gid=$(printf '%s\n' "$empeira_account" | cut -d : -f 4)
+  empeira_home=$(printf '%s\n' "$empeira_account" | cut -d : -f 6)
+  empeira_shell=$(printf '%s\n' "$empeira_account" | cut -d : -f 7)
+  empeira_uid_min=$(awk '$1 == "UID_MIN" && $2 ~ /^[0-9]+$/ { print $2 }' /etc/login.defs)
+  for empeira_number in "$empeira_uid" "$empeira_gid" "$empeira_uid_min"; do
+    case "$empeira_number" in ''|*[!0-9]*) fail 'unverifiable system SSH UID/GID range' ;; esac
+  done
+  test "$empeira_uid" -gt 0 && test "$empeira_uid" -lt "$empeira_uid_min" || fail 'expected a dedicated system UID'
+  test "$empeira_gid" -gt 0 || fail 'system SSH account must not use the root group'
+  test "$empeira_home" = /var/lib/empeira || fail 'changed system SSH home; expected /var/lib/empeira'
+  test "$empeira_shell" = /bin/bash && test -x "$empeira_shell" || fail 'changed system SSH shell; expected /bin/bash'
+  empeira_shadow=$(getent shadow empeira) || fail 'cannot verify the system SSH password lock'
+  empeira_password=$(printf '%s\n' "$empeira_shadow" | cut -d : -f 2)
+  case "$empeira_password" in \!*|\**) ;; *) fail 'system SSH password must stay locked' ;; esac
+  unset empeira_shadow empeira_password empeira_account
+  test ! -L /var/lib/empeira || fail 'system SSH home is a symlink'
+  if test "$1" = creating && test ! -e /var/lib/empeira; then return; fi
+  test -d /var/lib/empeira || fail 'system SSH home is missing or not a directory'
+  test "$(stat -c '%u:%g:%a' /var/lib/empeira)" = "$empeira_uid:$empeira_gid:700" || fail 'system SSH home ownership or permissions changed'
+}

data/resources/nodes/management/system_home.sh

@@ -0,0 +1,15 @@
+# Cloud-init system users deliberately omit ssh_authorized_keys and home creation.
+verify_account creating
+if test ! -e /var/lib/empeira; then
+  install -d -m 0700 -o "$empeira_uid" -g "$empeira_gid" /var/lib/empeira
+fi
+verify_account verified
+test ! -e /var/lib/empeira/.ssh && test ! -L /var/lib/empeira/.ssh || fail 'preexisting system SSH key directory'
+install -d -m 0700 -o "$empeira_uid" -g "$empeira_gid" /var/lib/empeira/.ssh
+install -m 0600 -o "$empeira_uid" -g "$empeira_gid" /etc/empeira/management/system_authorized_keys /var/lib/empeira/.ssh/authorized_keys
+for empeira_profile in .bashrc .bash_profile .profile; do
+  if test -f "/etc/skel/$empeira_profile" && test ! -e "/var/lib/empeira/$empeira_profile"; then
+    test ! -L "/etc/skel/$empeira_profile" && test ! -L "/var/lib/empeira/$empeira_profile" || fail 'unsafe shell initialization path'
+    install -m 0600 -o "$empeira_uid" -g "$empeira_gid" "/etc/skel/$empeira_profile" "/var/lib/empeira/$empeira_profile"
+  fi
+done

data/resources/nodes/rpm/Containerfile

@@ -0,0 +1,10 @@
+ARG EMPEIRA_BASE_NODE=@BASE_IMAGE@
+FROM ${EMPEIRA_BASE_NODE}
+RUN dnf install -y ca-certificates openssh-server systemd dbus iproute iputils bind-utils procps-ng sudo mlocate && dnf clean all
+RUN command -v curl || dnf install -y curl
+COPY node-start /usr/local/libexec/empeira-node-start
+COPY node-connect /usr/local/libexec/empeira-ssh-connect.rb
+COPY sshd_config /etc/ssh/sshd_config
+RUN chmod 0755 /usr/local/libexec/empeira-node-start && rm -f /etc/ssh/ssh_host_* && systemctl enable sshd.service
+ENTRYPOINT ["/usr/local/libexec/empeira-node-start"]
+CMD ["/usr/sbin/sshd", "-D", "-e"]