SYD-PTY(1)

NAME

syd-pty - PTY to STDIO bidirectional forwarder

SYNOPSIS

syd-pty [-dh] -i <pty-fd> [-x <x-size>] [-y <y-size>]

DESCRIPTION

Forwards data between given pty(7) main file descriptor and stdio(3).

OPTIONS

-h | Display help.
-d | Run in debug mode without confinement.
-i pty-fd | PTY main file descriptor.
-x x-size | Specify window row size (default: inherit).
-y y-size | Specify window column size (default: inherit).

USAGE

syd-pty(1) is not meant to be used as a standalone tool. Syd invokes syd-pty(1) at startup when PTY sandboxing is set to on with sandbox/pty:on. See PTY SANDBOXING section in syd(7) manual page for more information. If you want to use syd-pty(1) in your own project, create a new pseudoterminal with posix_openpt(3) or openpty(3) and pass main end of file descriptor pair to syd-pty(1) with -i <pty-fd> argument. syd-pty(1) is going to set terminal to raw mode and make no attempt to save/reset original terminal settings which is caller's responsibility.

IMPLEMENTATION

syd-pty(1) is designed for performance, security, and privacy, using edge-triggered epoll(7) for event notification and fully asynchronous operations to handle pseudoterminal activities without blocking. It transfers data with zero-copy splice(2), moving bytes directly between file descriptors within kernel without exposing plaintext in user space. Two pairs of pipes carry bidirectional traffic between pty(7) and stdio(3). execution environment is confined with seccomp(2) and landlock(7), restricting system calls and file access to minimum required.

SECURITY

syd-pty(1) applies multiple confinement layers to mitigate risks associated with running outside Syd sandbox, preventing potential Meddler-in-the-Middle (MITM) attacks against containers. Linux capabilities(7) are dropped early and no-new-privs attribute is set so no unwanted capability leaks into the process. TOSTOP flag is set for terminal to disable background processes from writing. Resource limits RLIMIT_FSIZE, RLIMIT_NOFILE, RLIMIT_NPROC, RLIMIT_LOCKS, RLIMIT_MEMLOCK, and RLIMIT_MSGQUEUE are set to zero to prevent file/fd/process/lock/msgqueue creation inside main loop. seccomp(2) filters are configured to allow only required syscalls. Executable memory is disallowed to prevent code injection attacks. landlock(7) and namespaces(7), if available, enforce further restrictions by disallowing all filesystem and network access, providing an additional layer of security. Additionally, main PTY file descriptor is placed into exclusive mode via TIOCEXCL ioctl(2) request. This prevents any further opens of secondary PTY device (save for processes with CAP_SYS_ADMIN capability), thereby preventing unauthorized eavesdropping or input injection at device layer. Binary is also re-executed from a sealed memfd_create(2) file descriptor to guard against CVE-2019-5736. These combined techniques ensure that even if syd-pty(1) is compromised, scope of malicious actions is significantly limited, maintaining integrity and security of the system.

ENVIRONMENT

SYD_PTY_DEBUG | Run in debug mode without confinement, equivalent to -d option.
 | This is ignored unless Syd is built with trusted Cargo feature.
SYD_PTY_RULES | Print seccomp rules in human-readable format to standard error at startup.

BUGS

splice(2) support for ttys was removed in commit 36e2c7421f02a22f71c9283e55fdb672a9eb58e7 (merged for Linux 6.5) and later restored in commit 9bb48c82aced07698a2d08ee0f1475a6c4f6b266 (merged for Linux 6.6). When running under a problematic Linux kernel syd-pty(1) will exit with 22, aka EINVAL or Invalid argument. See following links for more information:

•   https://git.kernel.org/linus/36e2c7421f02a22f71c9283e55fdb672a9eb58e7
•   https://git.kernel.org/linus/9bb48c82aced07698a2d08ee0f1475a6c4f6b266

SEE ALSO

syd(1), syd(2), syd(7), stdio(3), pty(7)

syd homepage: https://sydbox.exherbo.org/

AUTHORS

Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and on Radicle at rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF. Bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat or in #sydbox:mailstation.de on Matrix.