LEARN MORE

Security

Kiri runs a virtual machine, containers that can be privileged, and a local certificate authority on your Mac. This page explains the boundaries between them, what each one stops, and how Kiri makes sure the app you install and update is really Kiri.

The boundaries

There are three walls between a container and your Mac. The container runs in its own namespaces and cgroup, with a reduced set of capabilities and a syscall filter. All containers run inside one Linux VM, made with Apple’s Virtualization.framework. And the only way out of the VM to the Mac is vsock, which containers can’t open.

Containers live in the VM; the guest agent talks to the daemon on the Mac over vsock. A container's own vsock and io_uring calls are refused, so it can't reach the Mac that way, privileged or not.

The daemon runs as your user, not as root, and its socket at ~/.kiri/run/docker.sock is readable and writable only by you (mode 0600). Its private state (the certificate authority’s key, the proxy settings) is always under your home folder, even if KIRI_SOCKET moves the socket somewhere else.

Inside the VM

Containers start the way Docker’s do:

Docker’s default capabilities: CHOWN, DAC_OVERRIDE, FOWNER, FSETID, KILL, SETGID, SETUID, SETPCAP, NET_BIND_SERVICE, NET_RAW, SYS_CHROOT, MKNOD, AUDIT_WRITE, SETFCAP. --cap-add and --cap-drop change them.
A default seccomp filter, after Docker’s profile. System calls that reach outside the container’s namespaces (kernel keyrings, modules, the clock, swap, new mount and user namespaces, io_uring, bpf) fail with EPERM, unless the container holds the capability that makes them legitimate.
--read-only, --security-opt no-new-privileges, --pids-limit and the memory and CPU limits work as in Docker.

--privileged and --security-opt seccomp=unconfined turn off the default profile, but not the boundary to the Mac. Every container, whatever its capabilities, still has:

Refused	Why
`socket(AF_VSOCK, …)`	vsock isn’t namespaced. With it, a container could dial the Mac’s side directly: the `host.docker.internal` relay, the SSH agent, the control channel, past `--network none`. It fails with `EAFNOSUPPORT`.
`io_uring_setup`, `io_uring_enter`, `io_uring_register`	io_uring can create a socket without the system call a filter sees, so it would get round the vsock rule.

Your SSH agent reaches only the containers that mount /run/host-services/ssh-auth.sock. See SSH agent.

The certificate authority

For HTTPS, Kiri makes its own certificate authority once, “Kiri Local Certificate Authority”, and keeps it in ~/.kiri/tls. macOS only trusts it after you turn on HTTPS in Settings → Domains and enter your password.

Its name constraints let it vouch for *.kiri.local and *.kiri.localhost and nothing else. Every IP address is excluded too. So even if its key leaked, it couldn’t be used to impersonate your bank, github.com, or any other site.

Signed releases and verified updates

Kiri.app and its disk images are signed with a Developer ID and notarized by Apple.

Before an update installs, Kiri checks that the download matches the SHA-256 in the release feed, that it’s signed by the same identity as the Kiri you already have (a valid signature from anyone else isn’t enough), that Gatekeeper accepts its notarization, and that it is exactly the version the feed promised and newer than yours. The checks run again just before the swap. The install script does the SHA-256, signature and notarization checks too. See Updates.

Kiri Lite downloads the docker CLI, Compose and buildx on first open, and refuses any file whose SHA-256 isn’t the one pinned in the app.

Linux and Windows

On a Linux host there’s no VM: containers share the host’s kernel, with the same namespaces, capabilities and seccomp filter. Images and containers live in /var/lib/kiri (mode 0710) and the daemon’s state in /var/lib/kiri-daemon (0700).

On Windows, kiri-win.exe’s named pipe grants access only to you, SYSTEM and Administrators, and refuses remote clients. Kiri’s own WSL distro turns WSL interop off, so a process inside it can’t start Windows programs. The Windows installer isn’t signed, so its updates are checked by HTTPS and SHA-256, and by the MSI’s own upgrade code and version.

Report a vulnerability

Please don’t post a vulnerability in Feedback or anywhere public. Report it privately through GitHub’s private vulnerability reporting on Kiri’s repository (Security → Report a vulnerability).

Include what you found, how to reproduce it, and your Kiri version (Settings → About in the window). You should get a reply within a few days, and a fix or a plan once the issue is confirmed. Reporters are credited in the release notes unless they’d rather not be.

Security fixes go into the latest release, so please update before reporting. In scope: escaping a container or the VM to the Mac; the daemon socket, the HTTP and HTTPS router, DNS and the certificate authority; the installer, kiri setup and auto-update.