pidvault

Per-shell access to an encrypted SSH configuration directory.

The problem

You did the right thing: your SSH key has a good passphrase. Then you added it to ssh-agent (or your desktop did it for you) so you would not have to type it forty times a day — and from that moment the unlocked key is available to every process running as your user, for as long as you are logged in:

• the AI coding agent you let loose in a repository,
• your web browser, and that strange extension you decided you needed,
• the install script you downloaded with curl and piped to /bin/sh,
• every npm install postinstall hook, editor plugin and build script you run.

None of them have to ask. $SSH_AUTH_SOCK points at the agent, and a process that was not given the variable finds it in /proc/<pid>/environ of any of your shells. They cannot copy the key, but they do not need to: they can sign with it, which means logging in wherever you can and pushing wherever you can. The rest of ~/.ssh is no better guarded — a key without a passphrase is just a file to read, one ProxyCommand added to ~/.ssh/config runs code the next time you connect, and an open ControlMaster connection lets anyone run commands on that host without any key at all.

None of this is a bug. On Unix, the boundary is the user id, and everything you run is you.

What pidvault does instead

Access is granted per shell, not per login. A shell that has run pidvault unlock, and every process it starts, sees your decrypted config under /run/pidvault/stored/default/ and can sign with the keys stored there — through pidvault's own agent, which answers only processes of unlocked shells. The keys themselves cannot be read, not even from an unlocked shell, so nothing running there can take them along. Every other process running as you sees an empty directory and an agent with no keys. With several vaults, each shell sees only the ones it unlocked: one shell can have your GitHub key and another your production keys.

What it does not do

pidvault is not the perfect solution. It is an attempt to make this noticeably better without making SSH painful to work with: you unlock once per shell, and everything else behaves as before. It draws the line at the shell you unlocked, and a lot is still yours to get right:

• What you do in an unlocked shell. Anything started there can sign with your keys while the shell is unlocked, including the AI agent or the curl | sh you run in it. It cannot copy them, but it can change the vault, and whatever it plants there is still there in the next shell you unlock. Keep a shell for SSH and do the risky things elsewhere.
• A replaced ssh, or strange things in $PATH. Your own processes can write to ~/.local/bin, ~/.bashrc and the other files your shell trusts. An alias, a function or a binary planted there runs inside the next shell you unlock, and pidvault cannot tell it from the real thing.
• The pidvault block in ~/.ssh/config. It is editable the same way, and an entry placed above it wins. sudo chattr +i ~/.ssh ~/.ssh/config stops that; authorized_keys and known_hosts stay editable in place.
• Watching or taking over an unlocked shell. A process that can trace the shell can act as it, so unlock refuses unless kernel.yama.ptrace_scope is at least 1 (Ubuntu's default); even then the shell's ancestors, such as the terminal emulator, can. On X11, any program on your display can read the passphrase as you type it.
• Root. Anything that is, or can become, root is out of scope. That includes every process of yours when you are in the docker group, as most developers are: one docker run --privileged --pid=host makes it root. The groups lxd, libvirt and disk, and sudo without a password, do the same. Rootless Docker and Podman do not: their containers have only your own powers, and are not started by your shell, so the vaults stay closed to them. In the docker group pidvault still keeps your secrets from programs that read the files they know, but not from one that sets out to get past it.

The full list, with what each guarantee rests on, is in docs/security-design.md.

Installing

For Ubuntu 24.04 or later, on amd64, from the project's signed apt repository:

sudo curl -fsSLo /etc/apt/keyrings/pidvault.asc https://torstei.github.io/pidvault/pidvault.asc
echo "deb [signed-by=/etc/apt/keyrings/pidvault.asc] https://torstei.github.io/pidvault stable main" \
  | sudo tee /etc/apt/sources.list.d/pidvault.list
sudo apt update && sudo apt install pidvault

The repository is signed with the key with fingerprint D1434A919B60EEC6384F3CB716EFFB5096BD7539; check it with gpg --show-keys /etc/apt/keyrings/pidvault.asc before trusting it. The same key is in this repository as packaging/pidvault-apt.asc. Each .deb on the releases page also carries a build attestation: gh attestation verify pidvault_*.deb --repo torstei/pidvault shows that it was built by this repository's release workflow, and from which commit.

Installing starts the service. Upgrading restarts it, which locks every shell.

Moving from sshvault

pidvault was called sshvault up to 0.3.1. Its apt repository moved with the name, so the old one gets no more updates. Swap the source; the signing key is the same:

sudo rm /etc/apt/sources.list.d/sshvault.list /etc/apt/keyrings/sshvault.asc

then follow Installing. Installing pidvault removes sshvault and takes over its vaults, which keep their passphrases. What is left is the paths in your own files. Replace the sshvault block at the top of ~/.ssh/config with the output of pidvault stub, then, in a shell with every vault unlocked:

This is the beginning of the README. Read the rest at the original. Read the full README ↗