ttyspy.md

Architecture

The sshd on the logged host should be configured to launch ttyspy with ForceCommand, and have PermitRootLogin no.

               ┌───────────────────────── yama ──────────────────────────┐
               │ ┌────────┐                           other ttyspys      │
 ssh client ───┼─▶  sshd  │                           │     │     │      │
               │ └┬───────┘                           │     │     │      │
               │  │ForceCommand ttyspy    domain      │     │     │      │
               │  │      ┌──────────┐     socket  ┌───▼─────▼─────▼───┐  │
               │  └──────▶  ttyspy  ├─────────────▶      ttyspyd      │  │
               │         └──────────┘             └─────┬─────────────┘  │
               └────────────────────────────────────────┼────────────────┘
                                                        │                 
                                                        │ https           
                                                        │                 
               ┌─────────────────────  log server  ─────┼────────────────┐
               │                                        │                │
               │                                        │                │
               │                            ┌───────────▼─────────────┐  │
               │                            │ ttyspy session receiver │  │
               │                            └─────────────────────────┘  │
               │                                                         │
               │                                                         │
               └─────────────────────────────────────────────────────────┘

When invoked by the sshd, ttyspy will:

1. Check if the logged in user is root, and if so, skip logging entirely.
2. If the stdin is not a tty, it will log the SSH_ORIGINAL_COMMAND before executing it.
3. Otherwise, it will act similar to script(1), and log the terminal session.

Logging configuration

ttyspyd and the session_receiver go server require you to correctly set up TLS for it to work—it is not possible to configure it to skip certificate validation on either side. A test CA and client and server certificates (latter with the CN server.test) are provided in the repo. On the client side, be sure to add a server.test entry in your /etc/hosts when testing.

You need:

1. A client certificate (with X509v3 clientAuth extended key usage) signed by a CA
2. A server certificate signed by a CA

If you're unfamiliar with TLS certificate authentication, the client and server certs do not have to be signed by the same CA. The CA file passed to session_receiver is used to validate the client cert, and the CA passed to ttyspyd is used to validate the server cert. ttyspyd will use the standard curl bundle for certificate auth if you don't give it a CA bundle.

The logging server only has a route defined for POSTing to /transcript, so endpoint in ttyspy.conf will always be https://{server}:{port}/transcript.