rsync/support/rrsync

#!/usr/bin/env python3

# Restricts rsync to subdirectory declared in .ssh/authorized_keys.  See
# the rrsync man page for details of how to make use of this script.

# NOTE: install python3 braceexpand to support brace expansion in the args!

# Originally a perl script by: Joe Smith <js-cgi@inwap.com> 30-Sep-2004
# Python version by: Wayne Davison <wayne@opencoder.net>

# You may configure these 2 values to your liking.  See also the section of
# short & long options if you want to disable any options that rsync accepts.
RSYNC = '/usr/bin/rsync'
LOGFILE = 'rrsync.log' # NOTE: the file must exist for a line to be appended!

# The following options are mainly the options that a client rsync can send
# to the server, and usually just in the one option format that the stock
# rsync produces. However, there are some additional convenience options
# added as well, and thus a few options are present in both the short and
# long lists (such as --group, --owner, and --perms).

# NOTE when disabling: check for both a short & long version of the option!

### START of options data produced by the cull-options script. ###

# To disable a short-named option, add its letter to this string:
short_disabled = 's'

# These are also disabled when the restricted dir is not "/":
short_disabled_subdir = 'KLk'

# These are all possible short options that we will accept (when not disabled above):
short_no_arg = 'ACDEHIJKLNORSUWXbcdgklmnopqrstuvxyz' # DO NOT REMOVE ANY
short_with_num = '@B' # DO NOT REMOVE ANY

# To disable a long-named option, change its value to a -1.  The values mean:
# 0 = the option has no arg; 1 = the arg doesn't need any checking; 2 = only
# check the arg when receiving; and 3 = always check the arg.
long_opts = {
  'append': 0,
  'backup-dir': 2,
  'block-size': 1,
  'bwlimit': 1,
  'checksum-choice': 1,
  'checksum-seed': 1,
  'compare-dest': 2,
  'compress-choice': 1,
  'compress-level': 1,
  'compress-threads': 1,
  'copy-dest': 2,
  'copy-devices': -1,
  'copy-unsafe-links': 0,
  'daemon': -1,
  'debug': 1,
  'delay-updates': 0,
  'delete': 0,
  'delete-after': 0,
  'delete-before': 0,
  'delete-delay': 0,
  'delete-during': 0,
  'delete-excluded': 0,
  'delete-missing-args': 0,
  'dirs': 0,
  'existing': 0,
  'fake-super': 0,
  'files-from': 3,
  'force': 0,
  'from0': 0,
  'fsync': 0,
  'fuzzy': 0,
  'group': 0,
  'groupmap': 1,
  'hard-links': 0,
  'iconv': 1,
  'ignore-errors': 0,
  'ignore-existing': 0,
  'ignore-missing-args': 0,
  'ignore-times': 0,
  'info': 1,
  'inplace': 0,
  'link-dest': 2,
  'links': 0,
  'list-only': 0,
  'log-file': 3,
  'log-format': 1,
  'max-alloc': 1,
  'max-delete': 1,
  'max-size': 1,
  'min-size': 1,
  'mkpath': 0,
  'modify-window': 1,
  'msgs2stderr': 0,
  'munge-links': 0,
  'new-compress': 0,
  'no-W': 0,
  'no-implied-dirs': 0,
  'no-msgs2stderr': 0,
  'no-munge-links': -1,
  'no-r': 0,
  'no-relative': 0,
  'no-specials': 0,
  'numeric-ids': 0,
  'old-compress': 0,
  'one-file-system': 0,
  'only-write-batch': 1,
  'open-noatime': 0,
  'owner': 0,
  'partial': 0,
  'partial-dir': 2,
  'perms': 0,
  'preallocate': 0,
  'recursive': 0,
  'remove-sent-files': 0,
  'remove-source-files': 0,
  'safe-links': 0,
  'sender': 0,
  'server': 0,
  'size-only': 0,
  'skip-compress': 1,
  'specials': 0,
  'stats': 0,
  'stderr': 1,
  'suffix': 1,
  'super': 0,
  'temp-dir': 2,
  'timeout': 1,
  'times': 0,
  'use-qsort': 0,
  'usermap': 1,
  'write-devices': -1,
}

### END of options data produced by the cull-options script. ###

import os, sys, re, argparse, glob, socket, stat, time, subprocess
from argparse import RawTextHelpFormatter

# Held open across exec so rsync inherits them. Each entry pins a path
# validated_arg() approved; the corresponding arg passed to rsync is
# rewritten to /proc/self/fd/N so rsync's path resolution cannot be
# race-flipped after rrsync's realpath check, closing the realpath-vs-exec
# TOCTOU.
pinned_fds = []

# The inode-pin trick needs /proc/self/fd/N to be a Linux-style magic symlink
# whose readlink yields the open file's real path. macOS/BSD lack the directory
# entirely; Solaris HAS /proc/self/fd but its entries are not such symlinks (its
# readlink does not return the path), so an isdir() check is not enough -- probe
# the actual behaviour once against a known fd. Where it works we pin (and a
# later readlink failure is an anomaly that fails closed); where it does not we
# fall through to the unhardened path.
def _probe_proc_self_fd():
    try:
        fd = os.open('/', os.O_RDONLY)
    except OSError:
        return False
    try:
        return os.readlink('/proc/self/fd/%d' % fd) == '/'
    except OSError:
        return False
    finally:
        os.close(fd)

HAVE_PROC_SELF_FD = _probe_proc_self_fd()

try:
    from braceexpand import braceexpand
except:
    braceexpand = lambda x: [ DE_BACKSLASH_RE.sub(r'\1', x) ]

HAS_DOT_DOT_RE = re.compile(r'(^|/)\.\.(/|$)')
LONG_OPT_RE = re.compile(r'^--([^=]+)(?:=(.*))?$')
DE_BACKSLASH_RE = re.compile(r'\\(.)')

def safe_open_logfile():
    nofollow = getattr(os, 'O_NOFOLLOW', 0)
    try:
        st = os.lstat(LOGFILE)
    except OSError:
        return None
    if not stat.S_ISREG(st.st_mode):
        return None
    try:
        fd = os.open(LOGFILE, os.O_WRONLY | os.O_APPEND | nofollow)
    except OSError:
        return None
    st2 = os.fstat(fd)
    if not stat.S_ISREG(st2.st_mode) or st.st_dev != st2.st_dev or st.st_ino != st2.st_ino:
        os.close(fd)
        return None
    return os.fdopen(fd, 'a')

def main():
    if not os.path.isdir(args.dir):
        die("Restricted directory does not exist!")

    # The format of the environment variables set by sshd:
    #   SSH_ORIGINAL_COMMAND:
    #     rsync --server          -vlogDtpre.iLsfxCIvu --etc . ARG  # push
    #     rsync --server --sender -vlogDtpre.iLsfxCIvu --etc . ARGS # pull
    #   SSH_CONNECTION (client_ip client_port server_ip server_port):
    #     192.168.1.100 64106 192.168.1.2 22

    command = os.environ.get('SSH_ORIGINAL_COMMAND', None)
    if not command:
        die("Not invoked via sshd")
    if command == 'true':
        # Allow checking connectivity with "ssh <host> true".  (For example,
        # rsbackup uses this.)
        sys.exit(0)
    command = command.split(' ', 2)
    if command[0:1] != ['rsync']:
        die("SSH_ORIGINAL_COMMAND does not run rsync")
    if command[1:2] != ['--server']:
        die("--server option is not the first arg")
    command = '' if len(command) < 3 else command[2]

    global am_sender
    am_sender = command.startswith("--sender ") # Restrictive on purpose!
    if args.ro and not am_sender:
        die("sending to read-only server is not allowed")
    if args.wo and am_sender:
        die("reading from write-only server is not allowed")

    if args.wo or not am_sender:
        long_opts['sender'] = -1
    if args.no_del:
        for opt in long_opts:
            if opt.startswith(('remove', 'delete')):
                long_opts[opt] = -1
    if args.ro:
        long_opts['log-file'] = -1

    if args.dir != '/':
        global short_disabled
        short_disabled += short_disabled_subdir
        long_opts['copy-unsafe-links'] = -1

    short_no_arg_re = short_no_arg
    short_with_num_re = short_with_num
    if short_disabled:
        for ltr in short_disabled:
            short_no_arg_re = short_no_arg_re.replace(ltr, '')
            short_with_num_re = short_with_num_re.replace(ltr, '')
        short_disabled_re = re.compile(r'^-[%s]*([%s])' % (short_no_arg_re, short_disabled))
    short_no_arg_re = re.compile(r'^-(?=.)[%s]*(e\d*\.\w*)?$' % short_no_arg_re)
    short_with_num_re = re.compile(r'^-[%s]\d+$' % short_with_num_re)

    log_fh = safe_open_logfile()

    try:
        os.chdir(args.dir)
    except OSError as e:
        die('unable to chdir to restricted dir:', str(e))

    rsync_opts = [ '--server' ]
    rsync_args = [ ]
    saw_the_dot_arg = False
    last_opt = check_type = None

    for arg in re.findall(r'(?:[^\s\\]+|\\.[^\s\\]*)+', command):
        if check_type:
            rsync_opts.append(validated_arg(last_opt, arg, check_type))
            check_type = None
        elif saw_the_dot_arg:
            # NOTE: an arg that starts with a '-' is safe due to our use of "--" in the cmd tuple.
            try:
                b_e = braceexpand(arg) # Also removes backslashes
            except: # Handle errors such as unbalanced braces by just de-backslashing the arg:
                b_e = [ DE_BACKSLASH_RE.sub(r'\1', arg) ]
            for xarg in b_e:
                rsync_args += validated_arg('arg', xarg, wild=True)
        else: # parsing the option args
            if arg == '.':
                saw_the_dot_arg = True
                continue
            rsync_opts.append(arg)
            if short_no_arg_re.match(arg) or short_with_num_re.match(arg):
                continue
            disabled = False
            m = LONG_OPT_RE.match(arg)
            if m:
                opt = m.group(1)
                opt_arg = m.group(2)
                ct = long_opts.get(opt, None)
                if ct is None:
                    break # Generate generic failure due to unfinished arg parsing
                if ct == 0:
                    continue
                opt = '--' + opt
                if ct > 0:
                    if opt_arg is not None:
                        rsync_opts[-1] = opt + '=' + validated_arg(opt, opt_arg, ct)
                    else:
                        check_type = ct
                        last_opt = opt
                    continue
                disabled = True
            elif short_disabled:
                m = short_disabled_re.match(arg)
                if m:
                    disabled = True
                    opt = '-' + m.group(1)

            if disabled:
                die("option", opt, "has been disabled on this server.")
            break # Generate a generic failure

    if not saw_the_dot_arg:
        die("invalid rsync-command syntax or options")

    if args.dir != '/':
        # A restricted dir denies device/special creation, but `-a` (-rlptgoD)
        # bundles -D into the client's short-option string, so rejecting -D
        # outright would break every `rsync -a` to/from a restricted rrsync.
        # Force --no-D instead: it follows the client's options, so it strips
        # the device/special semantics (devices/specials are skipped, not
        # created) while the rest of the transfer proceeds normally.
        rsync_opts.append('--no-D')

    if args.munge:
        rsync_opts.append('--munge-links')
    
    if args.no_overwrite:
      rsync_opts.append('--ignore-existing')

    if not rsync_args:
        rsync_args = [ '.' ]

    cmd = (RSYNC, *rsync_opts, '--', '.', *rsync_args)

    if log_fh:
        now = time.localtime()
        host = os.environ.get('SSH_CONNECTION', 'unknown').split()[0] # Drop everything after the IP addr
        if host.startswith('::ffff:'):
            host = host[7:]
        try:
            host = socket.gethostbyaddr(socket.inet_aton(host))
        except:
            pass
        log_fh.write("%02d:%02d:%02d %-16s %s\n" % (now.tm_hour, now.tm_min, now.tm_sec, host, str(cmd)))
        log_fh.close()

    # NOTE: This assumes that the rsync protocol will not be maliciously hijacked.
    if args.no_lock:
        os.execlp(RSYNC, *cmd)
        die("execlp(", RSYNC, *cmd, ')  failed')
    # pass_fds keeps the inode-pinning O_PATH fds open across the spawn so
    # /proc/self/fd/N in the cmd resolves correctly in the child. See the
    # pinned_fds comment near the top.
    child = subprocess.run(cmd, pass_fds=tuple(pinned_fds))
    if child.returncode != 0:
        sys.exit(child.returncode)


def validated_arg(opt, arg, typ=3, wild=False):
    if opt != 'arg': # arg values already have their backslashes removed.
        arg = DE_BACKSLASH_RE.sub(r'\1', arg)

    orig_arg = arg
    if arg.startswith('./'):
        arg = arg[1:]
    arg = arg.replace('//', '/')
    is_absolute_arg = args.absolute and opt == 'arg' and args.dir != '/' and (arg == args.dir or arg.startswith(args.dir_slash))
    if not is_absolute_arg:
        arg = arg.lstrip('/')
    if args.dir != '/':
        if HAS_DOT_DOT_RE.search(arg):
            die("do not use .. in", opt, "(anchor the path at the root of your restricted dir)")

    if wild:
        got = glob.glob(arg)
        if not got:
            got = [ arg ]
    else:
        got = [ arg ]

    ret = [ ]
    for arg in got:
        if args.dir != '/' and arg != '.' and (typ == 3 or (typ == 2 and not am_sender)):
            arg_has_trailing_slash = arg.endswith('/')
            if arg_has_trailing_slash:
                arg = arg[:-1]
            else:
                arg_has_trailing_slash_dot = arg.endswith('/.')
                if arg_has_trailing_slash_dot:
                    arg = arg[:-2]
            real_arg = os.path.realpath(arg)
            if arg != real_arg and not real_arg.startswith(args.dir_slash):
                if not (is_absolute_arg and real_arg == args.dir):
                    die('unsafe arg:', orig_arg, [arg, real_arg])
            # Inode-pin the validated path so an attacker cannot flip a
            # path component AFTER realpath validates it but BEFORE the
            # exec'd rsync resolves it.
            #
            # CRITICAL: open with O_RDONLY (not O_PATH).  An O_PATH fd
            # holds a path/dentry reference and /proc/self/fd/N for an
            # O_PATH fd re-resolves the path on open -- which means the
            # race window stays open across the exec.  A regular
            # O_RDONLY fd holds an open file (inode-bound), and
            # /proc/self/fd/N for a regular fd references the inode
            # directly -- exactly the race-closing primitive we need.
            #
            # O_NOFOLLOW on this open means a symlink that raced into
            # place between realpath and this open is refused at the
            # leaf.  A subsequent fstat() + readlink-of-fd verifies the
            # pinned inode is still within the restricted tree (a
            # parent-component race that landed on an in-tree symlink
            # but outside-tree target would surface here).
            #
            # /proc/self/fd/N then routes the exec'd rsync's open
            # through the kernel's magic link to the SAME pinned inode
            # regardless of any subsequent flip; the race is closed.
            #
            # Linux-only (O_PATH/proc trick is Linux specific); on
            # non-Linux fall through to the unhardened path.  For paths
            # that don't exist yet (receiver-side new dest) os.open
            # fails -- we skip pinning there; the new-dest race is a
            # separate concern.
            try:
                try:
                    fd = os.open(real_arg, os.O_RDONLY | os.O_NOFOLLOW)
                except IsADirectoryError:
                    fd = os.open(real_arg,
                                 os.O_RDONLY | os.O_NOFOLLOW | os.O_DIRECTORY)
            except FileNotFoundError:
                # In --sender mode the path MUST exist (we're reading
                # from it) -- ENOENT here means the rename-based race
                # caught a transient gap in the flipper's swap.  Die.
                if am_sender:
                    die('post-realpath open failed (race detected):',
                        orig_arg, 'No such file or directory')
                # Receiver-side new destination: the leaf has no inode to pin
                # yet, but pin its existing PARENT directory and route the
                # exec'd rsync's creation through /proc/self/fd/<parent>/<leaf>,
                # so a parent-component flip after realpath can't redirect the
                # new file/dir out of the tree.  Linux-only (the /proc magic
                # link); elsewhere, or if the parent itself doesn't exist yet
                # (a deeper -R new path), fall through unpinned as before.
                fd = None
                leaf = os.path.basename(real_arg)
                if HAVE_PROC_SELF_FD and leaf and leaf not in ('.', '..'):
                    try:
                        pfd = os.open(os.path.dirname(real_arg) or '/',
                                      os.O_RDONLY | os.O_NOFOLLOW | os.O_DIRECTORY)
                    except OSError:
                        pfd = -1
                    if pfd >= 0:
                        try:
                            ppath = os.readlink('/proc/self/fd/%d' % pfd)
                        except OSError as e:
                            os.close(pfd)
                            die('post-pin readlink failed (race?):',
                                orig_arg, e.strerror)
                        # The pinned parent must be the tree root or under it.
                        if ppath != args.dir and not ppath.startswith(args.dir_slash):
                            os.close(pfd)
                            die('post-pin path escaped tree (race?):',
                                orig_arg, ppath)
                        os.set_inheritable(pfd, True)
                        pinned_fds.append(pfd)
                        arg = '/proc/self/fd/%d/%s' % (pfd, leaf)
            except OSError as e:
                # ELOOP or anything else is a race signal: realpath
                # validated the path moments ago, but the open just
                # failed -- something flipped between the check and
                # the pin (typically a symlink-flip on the leaf).
                die('post-realpath open failed (race detected):',
                    orig_arg, e.strerror)
            if fd is not None:
                # The inode-pin trick (verify + route the exec'd rsync's open via
                # the /proc/self/fd magic link) is Linux-only.  Where /proc/self/fd
                # does not exist at all (the BSDs, Solaris, macOS, Cygwin, or a
                # /proc-less namespace) we cannot pin -- fall through to the
                # unhardened path (close the fd, keep the realpath-validated arg)
                # per the design note above.  But where /proc/self/fd DOES exist
                # (Linux), a readlink failure is an anomaly (sandbox/seccomp), not
                # a no-proc platform: fail CLOSED rather than silently unharden.
                if not HAVE_PROC_SELF_FD:
                    os.close(fd)            # no /proc/self/fd: run unpinned
                else:
                    try:
                        pinned_path = os.readlink('/proc/self/fd/%d' % fd)
                    except OSError as e:
                        os.close(fd)
                        die('post-pin readlink failed (race?):',
                            orig_arg, e.strerror)
                    # The pinned inode must live under args.dir_slash (or BE
                    # args.dir).  Catches a parent-component flip that landed
                    # inside an in-tree path but pointed outside.
                    if (not pinned_path.startswith(args.dir_slash)
                        and pinned_path != args.dir):
                        os.close(fd)
                        die('post-pin path escaped tree (race?):',
                            orig_arg, pinned_path)
                    os.set_inheritable(fd, True)
                    pinned_fds.append(fd)
                    arg = '/proc/self/fd/%d' % fd
            if arg_has_trailing_slash:
                arg += '/'
            elif arg_has_trailing_slash_dot:
                arg += '/.'
            if is_absolute_arg and arg == args.dir:
                arg = '.'
            elif opt == 'arg' and arg.startswith(args.dir_slash):
                arg = arg[args.dir_slash_len:]
                if arg == '':
                    arg = '.'
        ret.append(arg)

    return ret if wild else ret[0]


def lock_or_die(dirname):
    import fcntl, errno
    global lock_handle
    lock_handle = os.open(dirname, os.O_RDONLY)
    try:
        fcntl.flock(lock_handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except OSError as e:
        if e.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
            die('Another instance of rrsync is already accessing this directory.')
        # flock() is unavailable on this fd/platform -- e.g. Solaris returns
        # EBADF for flock() on a directory fd. The single-run lock is a
        # best-effort convenience (cf. -no-lock), not a security control, so
        # proceed without it rather than abort every transfer.
        os.close(lock_handle)
        lock_handle = None


def die(*msg):
    print(sys.argv[0], 'error:', *msg, file=sys.stderr)
    if sys.stdin.isatty():
        arg_parser.print_help(sys.stderr)
    sys.exit(1)


# This class displays the --help to the user on argparse error IFF they're running it interactively.
class OurArgParser(argparse.ArgumentParser):
    def error(self, msg):
        die(msg)


if __name__ == '__main__':
    our_desc = """Use "man rrsync" to learn how to restrict ssh users to using a restricted rsync command."""
    arg_parser = OurArgParser(description=our_desc, add_help=False)
    only_group = arg_parser.add_mutually_exclusive_group()
    only_group.add_argument('-ro', action='store_true', help="Allow only reading from the DIR. Implies -no-del and -no-lock.")
    only_group.add_argument('-wo', action='store_true', help="Allow only writing to the DIR.")
    arg_parser.add_argument('-munge', action='store_true', help="Enable rsync's --munge-links on the server side.")
    arg_parser.add_argument('-absolute', action='store_true', help="Allow transfer args to use absolute server paths under DIR.")
    arg_parser.add_argument('-no-del', action='store_true', help="Disable rsync's --delete* and --remove* options.")
    arg_parser.add_argument('-no-lock', action='store_true', help="Avoid the single-run (per-user) lock check.")
    arg_parser.add_argument('-no-overwrite', action='store_true', help="Prevent overwriting existing files by enforcing --ignore-existing")
    arg_parser.add_argument('-help', '-h', action='help', help="Output this help message and exit.")
    arg_parser.add_argument('dir', metavar='DIR', help="The restricted directory to use.")
    args = arg_parser.parse_args()
    args.dir = os.path.realpath(args.dir)
    args.dir_slash = args.dir + '/'
    args.dir_slash_len = len(args.dir_slash)
    if args.ro:
        args.no_del = True
    elif not args.no_lock:
        lock_or_die(args.dir)
    main()

# vim: sw=4 et