Skip to content
NAILS on GitHub
These docs describe NAILS 0.3, published so far as the release candidate v0.3.0-rc.3. They do not apply to v0.2.0, the latest stable release. Download and verify NAILS 0.3

Threat model

NAILS is built for one adversary: someone who gets offline access to the disks and firmware after the fact, typically by seizing a powered-off machine, and examines them to prove that a hidden session ever existed. They can image every disk, read every unencrypted block, log and filesystem journal, inspect the EFI system partition and the EFI variables, and compare the decoy with a plain installation. Any trace that shows a hidden session existed counts as evidence, even when the hidden data itself stays encrypted.

The adversary may also make you unlock the decoy once, by legal order or by demand, and then examine the unlocked decoy offline. That is the case NAILS is built for. See If you are made to unlock the decoy for what NAILS offers there and where it stops.

What anti-forensics and deniability mean here

Section titled “What anti-forensics and deniability mean here”

For NAILS, anti-forensics means one bounded thing: it narrows what an offline examination of the decoy can find. After a clean session on a correctly prepared decoy, the decoy disk holds nothing of the hidden session beyond a short, documented list of residual channels, and nothing that would start a session. NAILS does not make you invisible, and it does not protect against anyone with access to the running machine.

Plausible deniability is a property of the hidden volume, not of NAILS. Whatever deniability the hidden volume has comes from the storage backend you choose, for example a VeraCrypt hidden volume. NAILS encrypts nothing and adds nothing to the backend’s claim. What NAILS does is keep the session off the decoy, where any trace of it would be evidence. See also how NAILS compares with related tools.

Neither is a guarantee. Deniability does not end coercion. An adversary who believes a hidden volume exists can keep demanding credentials whatever you say, and if you are known to be able to run one, you may not be believed when there is none. An examiner who knows NAILS may believe a hidden volume exists without being able to prove it. Disclosure of the hidden volume’s credentials, continued coercion and repeated imaging of the disk are out of scope.

  • Keeping the hidden session’s files, logs, shell history and package builds off the decoy disk. They all land in the overlay’s upper layer on the hidden volume, which must be storage of its own.
  • Leaving no enabler on the decoy. There is no boot entry, initrd change, unit or binary that would start a hidden session. A line in the decoy’s /etc/crypttab or /etc/fstab that opens or mounts the hidden volume would be one, so the backend-entries check refuses activation while such a line exists. No flag overrides it.
  • Checking your own setup. nails check runs before entry, nails verify looks for known artifacts and nails rehearse plants a canary and searches the raw decoy disk for it.

NAILS does not tune individual applications. Every process of the hidden session starts inside the overlay, so whatever any program writes through the decoy’s mounted filesystems lands on the hidden volume. The question of which application leaks becomes the question of which writes go around the mount layer. That set is small and listed: the residual channels below, and the decoy’s other filesystems, which each get a fixed decision before the switch. The overlay does not isolate what the session shares with the decoy, such as its user account and network identity.

  • Anyone with access to the running machine, memory forensics or cold-boot attacks. A soft-reboot keeps RAM, so power off after a session.
  • Network and remote records. The hidden session shares the decoy’s kernel, machine ID, hostname, MAC addresses and, by default, its user account and home. Internet providers, VPNs and online services see whatever it does. What it sends through a shared account or sync client stays on the remote side, and a decoy sync client can pull it back onto the decoy disk.
  • Compelled disclosure of the hidden volume, physical or repeated coercion, or an adversary who images the disk more than once and compares the images.
  • A persistent decoy. A journal, syslog or audit log on the decoy disk records the soft-reboots. Activation refuses such a decoy unless you override it.
  • Firmware or hardware compromise, keyloggers, side channels or a compromised root account on the decoy.
  • Operator mistakes, such as skipping deactivation or leaving the hidden volume mounted.

The claims above hold only when all of these are true.

  • Outer encryption. The decoy disk uses full-disk encryption whose credentials unlock the decoy and nothing else. The hidden volume sits inside a deniable backend, for example a VeraCrypt hidden volume. NAILS does not provide encryption. The hidden volume page covers which backends work and their hazards.
  • An amnesic decoy. The decoy keeps no durable record of the session. That means a volatile journal, no classic syslog or audit daemon and no persistent crash dumps. NAILS enforces the load-bearing parts before activation. Prepare the decoy shows how on each platform.
  • No swap or hibernation on a decoy disk.
  • A volatile journal. The journal lives in RAM only, so what the decoy logs around each soft-reboot never reaches the disk. The way back deletes the journal the hidden session shared with the decoy, so the decoy’s journal starts again at the return.
  • Storage of its own, prepared elsewhere. The hidden volume is a device, partition or encrypted volume the decoy does not use. It was created on another computer or from a live system that writes nothing to this computer’s disk, never on the decoy itself. NAILS refuses a hidden volume on the decoy’s storage, but it cannot see what creating a volume on the decoy left behind.
  • A trusted root. The NAILS binary, its configuration and the hidden configuration on the hidden volume are intact. NAILS runs as root and does not check its own integrity.
  • A clean teardown. You deactivate or run nails emergency, then power off, before the machine can be taken. Both close the hidden volume, and powering off clears what a soft-reboot keeps in RAM. See ending a session.
  • systemd 254 or newer, for systemctl soft-reboot. Older hosts are refused.

The hidden volume must be storage of its own

Section titled “The hidden volume must be storage of its own”

Every write NAILS makes goes to the hidden volume, so every claim on this page assumes that the hidden volume is storage of its own. Before anything is written, init, activate, check and every other command that writes ask the attach gate, which refuses:

  • a folder, or a btrfs subvolume or bind mount of a filesystem the decoy uses
  • a filesystem the decoy’s fstab mounts, or a volume stacked on the decoy’s storage or swap
  • an unencrypted image file on a decoy filesystem
  • a filesystem that shows no disk it stores its data on, such as an overlay, FUSE, network or ZFS filesystem
  • a hidden volume with a second filesystem mounted over it

--no-preflight does not skip the gate. An encrypted container file on a decoy filesystem is accepted with a warning, since that filesystem’s journal and copy-on-write snapshots can keep old copies of the parts of the container that changed. --allow-decoy-storage turns the refusal of the decoy’s storage into a warning, for storage you know the decoy does not use. It never covers a folder, a covered volume, storage the gate cannot judge or the backend-entries check.

The gate judges only what this computer’s mount table, fstab, crypttab and sysfs describe. It cannot see a decoy filesystem mounted by hand and never listed, storage another operating system on the machine uses, or the traces that creating the volume on this computer left behind, such as the setup tools’ own files, shell history or a changed partition table. Only preparing the volume elsewhere avoids those traces: on another computer, or from a live system started from a USB stick. A live system writes to this computer’s disk too when you use it to change the disk’s partition table or to mount a decoy filesystem, for example to reach a container file there. First install from Tails shows the first installation of NAILS from Tails.

This is in scope when it happens once and the unlocked decoy is then examined offline. After a clean session on a correctly prepared decoy, the decoy disk holds nothing of the hidden session beyond the residual channels below, and nothing on it would start a session.

NAILS does not hide the setup itself. An unlocked decoy is still a machine with encryption tools, encryption headers and history. nails verify --offline --examiner lists these traces on an image of the decoy, so you can remove or explain each one beforehand.

For this case to hold, you have to:

  • use a deniable backend, and keep the decoy’s credentials apart from the hidden volume’s, so disclosing one never opens the other
  • run an amnesic decoy, deactivate cleanly and power off before the machine can be taken
  • run nails rehearse on the real machine and nails verify --offline --examiner on an image of the decoy before you rely on it, and remove or be ready to explain every trace they report
  • keep the decoy in plausible, regular use, so its logs account for the time the machine ran

These are not in scope:

  • The deniability of the hidden volume itself. It depends on the backend, not on NAILS, and NAILS adds nothing to the backend’s own claim. A LUKS volume is visibly an encrypted volume. For a VeraCrypt hidden volume, VeraCrypt’s hidden volume documentation says it “should be impossible to prove” that one exists, even with the outer volume mounted, provided its volume creation instructions and its security requirements for hidden volumes are followed. The hidden volume page covers VeraCrypt’s requirement for Linux.
  • Disclosure of the hidden volume’s credentials. Whoever has them sees everything, including NAILS and its configuration.
  • Physical coercion, or coercion that continues after the decoy is unlocked.
  • Repeated imaging. Two images taken before and after further use show which encrypted regions changed. An outer volume whose encrypted regions changed while its files did not is the classic way hidden volumes are found. Changes on the decoy that its own logs do not explain, such as clock and timer stamps and SMART power-on hours, also add up across sessions.
  • An examiner who knows NAILS. NAILS is public and relies on no secrecy. A knowledgeable examiner looks for NAILS’s own files and markers, a sudo record naming a binary on another volume, encryption tools with recent access times and random-looking disk space. NAILS keeps its own files and markers off the decoy and reports the others. Whether those have a plausible explanation is yours to establish, and the examiner may still believe a hidden volume exists without being able to prove it.

Some traces bypass the overlay. Each one is bounded by an assumption above or documented as a known gap. Several live only in RAM and are gone at power-off.

  • The decoy journal around each soft-reboot. A volatile journal keeps it in RAM. Keep the binary at a neutral path.
  • A volatile decoy journal that starts at the return, not at the boot. It lives in RAM only. Power off after the session.
  • The sudo log file and sudo I/O logging. Remove both from the decoy’s sudoers configuration.
  • Disks you mount during the hidden session. NAILS alerts on every read-write mount and offers an opt-in read-only mode.
  • Late kernel records imported by the decoy journal. The way back moves the journal’s kernel cursor past them. Only PID 1’s last generic lines and the hidden filesystem’s unmount line come after the cursor.
  • Network links, addresses, routes and tunnels the session set up. They stay until power-off. When the decoy’s NetworkManager starts, it records a link the session created, with the time, on the decoy disk. Before you deactivate, take down the connections and tunnels you brought up and delete the links you created, or deactivate with --poweroff, which powers off before the decoy’s NetworkManager starts. End a session that used the hidden network identity with --poweroff.
  • The soft-reboot counter (systemd 256 and newer) and boot ID. On a volatile decoy they live in RAM only. Power off after the session.
  • Login and boot records around a switch. On Debian and Ubuntu the way back makes them read as one clean power cycle. Records written after the way back still carry process numbers that continue from the decoy’s boot, on every platform. Power off after the session.
  • The decoy’s mounts, made again by the way back. They live in RAM only. Power off after the session.
  • EFI variables, the real-time clock and firmware storage. NAILS never writes EFI variables. Avoid firmware tools in the session.
  • Memory remanence. Power off after a session and leave the machine off for a few minutes. Boot the decoy with init_on_free=1.
  • Clock and timer stamps on the decoy. The session’s own stamps land in the upper layer. Use the decoy normally after a session, and expect timers to catch up at its next boot.
  • SMART power-on hours. There is no software fix. Keep the decoy in plausible, regular use.
  • Old copies of rewritten blocks on an SSD. With full-disk encryption on the decoy they are only ciphertext. Do not use TRIM on a volume that holds a hidden volume.

The full residual channels table in the repository also says why each channel survives the overlay and which check detects it.

  • Automated end-to-end tests run sessions in NixOS virtual machines and image the decoy disk afterwards. The hidden volume is LUKS2 with ext4, and in one test a VeraCrypt hidden volume opened with cryptsetup. Two of these tests check that a session leaves the files on the EFI system partition, the boot entries and the list of EFI variables as a plain reboot would.
  • Debian 13 and Ubuntu 24.04 virtual machines get a smoke run, which enters and leaves a session and checks the decoy disk image for leaks. A separate VM test, which runs outside CI, checks their login and boot records against a power-cycle control.
  • The full configuration was evaluated by hand once: a NixOS decoy with a tmpfs root, a VeraCrypt hidden volume opened with cryptsetup and dead-disk analysis of the decoy image. That evaluation predates the current whole-root design, which refuses a tmpfs root, and has to be repeated on a disk-backed decoy root.
  • Other backends and filesystems are not covered. The session is validated in virtual machines. The time to the login screen, GPU and Wi-Fi after the soft-reboot, TPM-sealed decoy roots and GRUB stay open until they are measured on real hardware.

Claims outside this scope are unverified. Before you rely on NAILS, run nails rehearse and nails verify on your own machine.