Skip to content

Capture With Least Privilege

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

A live capture needs raw-socket rights for one moment: opening the interface. Everything after that, the parsing of untrusted packets included, needs none. This page takes the rights away as early as sipnab allows, and narrows what the process can reach after that.

Step What it takes away Needs
Grant capture rights to the binary Running as root at all Linux, setcap
Let sipnab drop root Root after the interface opens Started as root
Read capture files only root can read Root while it reads the files Started as root, one open file per input
Confine it to a directory The rest of the file system Started as root
Bound the files it can open Files outside the paths the run names A kernel with Landlock
Bound the system calls it makes System calls outside a derived list A kernel with seccomp, a list derived on that host

Reading a capture file needs none of this: it is reading a file.

What ran: every command and output on this page ran on 2026-11-03 with sipnab 0.5.232 built from source, on Ubuntu 24.04 with Linux 6.8 (aarch64). That kernel has seccomp and no Landlock, so Bound the files it can open shows the refusal and not a confined run.

Before you start

  • Linux. File capabilities, Landlock and seccomp are Linux features. Every command on this page ran on Linux only.
  • sipnab on the capture host, as Installing sipnab says.
  • Root, or sudo, for the step you take. The table above names the steps that start as root.
  • setcap and getcap, for the first step. On Debian and Ubuntu the libcap2-bin package has them.
  • An interface that carries the traffic. ip -brief link lists the interfaces. The examples use eth0.
  • Nothing on any other system. Every step changes the capture host only: the capabilities of one binary, the user and root directory of one process, and the paths and system calls that process may use. No SIP server, relay or network device changes.

Grant capture rights to the binary

sipnab --setup-caps

It sets cap_net_raw,cap_net_admin+ep on the binary with setcap, re-running itself through sudo when it is not root, and exits. It prints nothing. Check the result:

getcap "$(command -v sipnab)"

It prints the binary's path followed by cap_net_admin,cap_net_raw=ep.

Then capture as your own user:

sipnab -N -d eth0 --duration 3 --no-cli-print

On a lab bridge, hepx, that printed:

INFO sipnab::capture::live: Capturing on 'hepx' (link_type=1, snaplen=65535)
INFO sipnab::capture::live: Live capture on 'hepx' finished: 0 packets, no drops
  • Replacing the binary clears its capabilities: an upgrade, a rebuild, a package update. Run --setup-caps again after each.
  • A file system mounted nosuid ignores file capabilities.
  • macOS and other systems without file capabilities run live capture under sudo.
  • Under systemd, AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN grants the same to a unit that runs as an ordinary user (Run sipnab as a service).

Let sipnab drop root after opening the interface

Started as root, sipnab opens the interface, then switches to an unprivileged user: nobody unless you name another with --user or [privilege] user.

sudo sipnab -N -d eth0 --duration 3 --no-cli-print

The log says which user it became. On the lab bridge:

INFO sipnab::privilege: Dropped privileges to user 'nobody' (uid=65534, gid=65534)
  • sipnab opens what the run reads by path before the drop: the capture device, a keylog file or FIFO, the config. A file the dropped user cannot reach is unreachable after that.
  • It creates -O and --split files after the drop, as the dropped user, so that user must be able to write their directory (An output file sipnab cannot create).
  • The dropped user usually cannot read your home directory, so the TUI's file browser (O) shows nothing there. Capture with capabilities instead.
  • --no-priv-drop (or [privilege] no_priv_drop = true) keeps root for the whole run, and the log says Privilege drop disabled (--no-priv-drop). --priv-drop turns the drop back on for one run when the file turns it off. The scanner-kill worker does not need either: sipnab opens its raw socket before the drop.

Commands that do not capture

Some commands open no capture and end before a capture would start. Since 0.5.256 the ones that listen or connect drop root too. A command that is not started as root changes in nothing.

Command Started as root
sipnab fleet serve Reads its key files and binds as root, then runs as --user, else nobody, before it opens the store or accepts
sipnab fleet inventory Reads the hosts file and every token file as root, then asks each instance as --user, else nobody
sipnab fleet verify Reads its key files as root, then lists and reads the history files as --user, else nobody
--vcon-forward, --vcon-fetch, --vcon-audio-fetch Reads its credential, key and CA files as root, then runs as --user, else [privilege] user, else nobody, before it creates a directory or connects
--relay-holdings, --relay-sessions Runs as --user, else [privilege] user, else nobody, before it asks the relay
--show-frame, --strip-secrets, --write-annotated, --find-in-files, --compare-captures Since 0.5.257: names and opens its capture files (and the notes file) as root, then runs as --user, else [privilege] user, else nobody, before it unpacks or parses any of them
--vcon-validate, --vcon-resign Since 0.5.257: reads the container's bytes (and the signing key and certificate) as root, then runs as --user, else [privilege] user, else nobody, before it parses them
  • A file the command reads once, such as a key, a token or a CA, can stay readable by root only.

  • What the command writes must belong to the user it runs as: the center's store and its directory, the forwarder's spool, and the directory that holds --vcon-fetch-out, --vcon-audio-fetch-out, --vcon-resign-out, or the copy --strip-secrets or --write-annotated writes.

  • When that user cannot write it, the command refuses to start, exits 2 and creates nothing. The message names the path and three ways out:

    --vcon-fetch: started as root, this command runs as user 'nobody', and 'nobody' cannot write in '/home/alice/vcons' (--vcon-fetch-out). Nothing was created. Choose one: chown nobody '/home/alice/vcons'; run it with --user alice, who can; or pass --no-priv-drop to keep root
    
  • The sipnab fleet commands read no configuration file. [privilege] user does not name their user: it is --user, else nobody.

  • sipnab fleet verify writes nothing. The user it runs as must read the history directory, every directory in it and every file in them. When that user cannot, the command refuses before it reads a history file, exits 2, and the message says cannot read with the path (Verify the history store).

  • Under sudo, the message names the calling user in --user when that user can write the path. Otherwise it prints --user USER.

  • --no-priv-drop keeps root, as before 0.5.256, and the command logs one warning line that says so.

  • On macOS a command started as root with no --user keeps root, as a capture does there, and logs one warning line.

  • --vcon-audio-fetch-local makes no connection, so it keeps the caller's user.

sipnab g729 install started as root downloads, checks and unpacks the package as --user, the config user or nobody, and root only checks the table file that user sends and writes it in place. That user must be able to write in TMPDIR and read the CA bundle. --from PATH and --no-priv-drop keep the caller's user (Install as root).

These commands still run as the user that started them, root included:

  • Commands that read no input from outside, or need root: --setup-caps, --uprobe-list, --mint-token, --dump-config, --vcon-spool-status, --journal-show, --revert-actions, --completions, --print-yang-module, sipnab fleet keygen and sipnab g729 status.

Run a command that parses a file as root

Purpose: run --show-frame, --strip-secrets, --write-annotated, --find-in-files, --compare-captures, --vcon-validate or --vcon-resign on a file only root can read, without parsing that file as root. Since 0.5.257 sipnab opens the file as root and parses it as another user.

Prerequisites:

  • sipnab 0.5.257 or later, started as root (with sudo, for example).
  • For a command that writes a file (--strip-secrets, --write-annotated, --vcon-resign-out): a directory for the output that the user the run drops to can write. No other system needs a change.

Steps:

  1. Choose the user the command runs as: --user USER, else [privilege] user in the config file, else nobody. --show-frame, --write-annotated and --vcon-validate read the config file for [privilege] only; if it does not load, they use --user, else nobody.

  2. Run the command and name the output in a directory that user can write. Here call.pcapng is a capture only root can read, in a directory you own:

    sudo sipnab --strip-secrets clean.pcapng -I call.pcapng --user "$SUDO_USER"
  3. A command that prints its answer needs no output directory:

    sudo sipnab --show-frame 'call.pcapng#12'

Verify: the output file belongs to the user the run dropped to (ls -l clean.pcapng). With --no-tui (-N), the log holds Dropped privileges to user 'nobody' before the command's result.

Troubleshoot:

  • The run exits 2 with a message that starts --strip-secrets: started as root: it stopped before it parsed or created anything. Use one of the three ways the message lists.
  • A gzip capture or an archive fails with Permission denied: sipnab unpacks it after the drop, into the temporary directory. Point TMPDIR at a directory the user the run drops to can write.
  • --find-in-files exits 2 and names the open-file limit: as root it opens every file before the drop. Raise the limit (ulimit -n), or sweep fewer files in one run.
  • --write-annotated says a note names another capture: after the drop, sipnab cannot compare two spellings of a path inside a directory the user cannot enter. Spell -I as the notes file spells the capture.
  • --no-priv-drop keeps root for the whole command, and the command prints one line that says so.

Read capture files only root can read

Purpose: read a set of captures, or an archive of them, that only root may open (mode 0600, owner root), while the run still drops to nobody or chroots before it parses a packet.

Prerequisites: started as root, as in the previous section. The open-file limit must hold one descriptor per input file plus 64 for the run itself.

Steps: name the files, a directory or an archive with -I, as an ordinary run does.

sudo sipnab -N -I /var/lib/captures/ring/ --user nobody

A root run that drops privileges or chroots opens every file of the set before it does either, and reads each one through the descriptor it opened then. A run that keeps its credentials (not root, or --no-priv-drop without --chroot) opens each file when it reaches it, as before.

Since 0.5.259 a root run that drops privileges reads none of those bytes as root: it opens the files, drops, and then unpacks, probes and reads them as the user it dropped to. The line Reading N capture files comes after Dropped privileges in the log.

  • The run raises its open-file soft limit as far as the hard limit when the set needs it. Above the hard limit the run stops before it reads anything, with exit 2.
  • The run unpacks an archive (.tar.gz, .zip, a .pcap.gz) after the drop, as the drop user, into a directory only its owner may enter (0700) holding files only its owner may read (0600), under TMPDIR. That user must be able to write TMPDIR: root's per-user temporary folder on macOS (under /var/folders, mode 0700) is not one it can reach, so set TMPDIR=/tmp there.
  • A --chroot run changes root and drops first too, and unpacks inside the new root, as the drop user, under TMPDIR as seen there (normally DIR/tmp on the host). Confine it to a directory says what DIR then needs.
  • The run reads the TLS secrets a pcapng carries in a Decryption Secrets Block through the descriptor it opened as root, so a root-only capture still decrypts.

Verify: with SIPNAB_LOG=info, the closing line counts every file as read in full, and no line says Skipping. On 2026-11-08 with sipnab built from source after 0.5.237, three root-only copies of one capture under a soft limit of 66:

INFO sipnab::app::bootstrap: Raised the open-file limit from 66 to 67: the 3 input file(s) are opened before the run confines itself
INFO sipnab::privilege: Dropped privileges to user 'nobody' (uid=65534, gid=65534)
INFO sipnab::capture::file: Read 21 packets: 3 of 3 file(s) read in full

Troubleshooting: under a hard limit of 66 the same run stopped with exit 2:

sipnab opens all 3 input file(s) before it drops root privileges or chroots, beside 64 descriptors of its own, and this process may hold at most 66 open files. Raise the limit (ulimit -n), read fewer files per run, or run as an ordinary user, which opens each file when it is read.

Raise the hard limit (ulimit -Hn, or LimitNOFILE= in a systemd unit), or split the set across runs. 0.5.239 and earlier opened every file after the first by path after the drop, and skipped a root-only one with Permission denied (No such file or directory under --chroot), the run ending with exit 1 and a line such as Read 2 packets: 1 of 2 file(s) read in full, 1 skipped.

When the drop user cannot write TMPDIR, the run stops with exit 1 at the first archive or .pcap.gz, before it unpacks anything:

-I/--input: cannot unpack '/var/lib/captures/a.pcap.gz': user 'nobody' cannot create files in the temporary directory '/var/folders/xy/T', where sipnab unpacks an archive or a compressed capture after it drops root. Set TMPDIR to a directory that user can write (TMPDIR=/tmp), or pass --user with a user who can write it

Run with TMPDIR=/tmp before the rest of the command (sudo TMPDIR=/tmp sipnab -N -I a.pcap.gz), or with --user naming a user that can write the directory. A capture that needs no unpacking reads whatever TMPDIR is.

Confine it to a directory

--chroot DIR (or [privilege] chroot) changes the root directory to DIR after the interface opens and before the drop.

sipnab looks the user up before it changes root, so DIR needs no etc/passwd: an empty directory works. 0.5.233 and earlier looked the user up inside DIR and stopped with Failed to drop privileges: User 'nobody' not found unless DIR held an etc/passwd naming the user.

A file run (-I) opens its files before it changes root and reads them through those descriptors, so DIR needs no copy of them. Since 0.5.259 an archive or a .pcap.gz unpacks after the chroot, as the drop user, into the temporary directory inside DIR: create it, writable by that user.

sudo mkdir -m 1777 /var/lib/sipnab/jail/tmp

Without it the run stops with exit 1 at the first such file, before it unpacks anything:

-I/--input: cannot unpack '/var/lib/captures/a.tgz': user 'nobody' cannot create files in the temporary directory '/tmp' inside --chroot '/var/lib/sipnab/jail', where sipnab unpacks an archive or a compressed capture after it drops root. Create '/var/lib/sipnab/jail/tmp' writable by that user (mode 1777), or set TMPDIR to such a directory inside '/var/lib/sipnab/jail'

The run removes what it unpacked from DIR/tmp when it ends. A capture that needs no unpacking reads with an empty DIR.

A TLS client that names no CA file of its own (a --hep-send-transport tls sender without --hep-tls-ca, an HTTPS [vcon_fetch] store without ca) trusts the host's CA bundle. A run with --chroot finds and reads that bundle before it changes root, so DIR needs no copy of it. 0.5.238 and earlier looked for it inside DIR and stopped with exit 2: Failed to create HEP sender: no system CA bundle found; name the collector's issuer with --hep-tls-ca. If no bundle exists outside DIR, sipnab still looks inside it.

A directory that does not exist stops the run with exit 1: Failed to chroot: chroot(/var/empty) failed: No such file or directory (os error 2). Debian and Ubuntu have no /var/empty. Make an empty directory for it:

sudo mkdir -p /var/lib/sipnab/jail
sudo sipnab -N -d eth0 --user nobody --chroot /var/lib/sipnab/jail --duration 3 --no-cli-print
INFO sipnab::privilege: Chrooted to /var/lib/sipnab/jail
INFO sipnab::privilege: Dropped privileges to user 'nobody' (uid=65534, gid=65534)

Any file the run writes after this, -O included, is a path inside DIR.

Bound the files it can open (Landlock)

--sandbox uses Linux's Landlock to limit which paths the process can open once startup is over, to the ones the run names: its inputs, outputs, key files and configuration.

  • --sandbox best-effort confines the run where the kernel has Landlock, and warns and runs unconfined where it does not.
  • --sandbox required refuses to capture without it, with exit 1.

On a kernel built without Landlock:

sipnab -N -I sample-call.pcap --sandbox required --report --no-cli-print
WARN sipnab::app::bootstrap: path sandbox NOT active: this kernel (6.8.12-rt-tegra) has no Landlock: it was built without Landlock support (CONFIG_SECURITY_LANDLOCK). The capture is running unsandboxed; `--sandbox required` refuses instead of continuing.
`--sandbox required` was given and no path sandbox is in force: this kernel (6.8.12-rt-tegra) has no Landlock: it was built without Landlock support (CONFIG_SECURITY_LANDLOCK). Refusing to capture. Use `--sandbox best-effort` to capture without one.

Rerun on 2026-11-08 on the same host (Linux 6.8.12-rt-tegra). The reason depends on the running kernel's release, from uname:

The version query returns Release The reason says
ENOSYS older than 5.13 this kernel (<release>) has no Landlock (needs 5.13 or newer)
ENOSYS 5.13 or newer this kernel (<release>) has no Landlock: it was built without Landlock support (CONFIG_SECURITY_LANDLOCK): a kernel upgrade does not help; a kernel built with that option does
ENOSYS unreadable both causes, and that sipnab could not read the release
EOPNOTSUPP any Landlock is compiled in but disabled; add it to the kernel's lsm= list to enable it

Before that change the text said needs 5.13 or newer for every ENOSYS, which on this 6.8 kernel was wrong. Check yours:

cat /sys/kernel/security/lsm

landlock must be in the list. Not run for this page: a run with Landlock in force.

Bound the system calls it makes (seccomp)

--seccomp installs a seccomp filter. Its two modes are two steps:

  1. --seccomp log allows every system call and records each one. It protects nothing. It exists to find out which calls your runs make.
  2. --seccomp enforce kills the process on a call outside an allowlist, which you derive on the host that runs the capture and name with SIPNAB_SECCOMP_ALLOWLIST: a file of syscall numbers, one per line, # comments allowed.

Without a list, enforce refuses to start, with exit 1:

`--seccomp enforce` was given and no syscall filter is in force: enforcement needs an allowlist derived ON THIS HOST, named by SIPNAB_SECCOMP_ALLOWLIST. The list that ships in this binary settled across sixteen shapes on one machine and killed the process on another of the same architecture, so it is a worked example rather than a list to enforce. Produce yours with scripts/derive-seccomp-allowlist.sh. Refusing to capture. Use `--seccomp off` to capture without one.

scripts/derive-seccomp-allowlist.sh <sipnab> <interface>, run as root, runs sipnab in sixteen shapes under --seccomp log, streams the log the records go to, and says whether the set of calls stopped growing.

Where the records go depends on the host, and the script finds out the same way you would:

sudo auditctl -s
  • A non-zero pid means an audit daemon holds the audit socket. The kernel hands it the records, and they land in its log (log_file in /etc/audit/auditd.conf, /var/log/audit/audit.log by default) as type=SECCOMP lines. The script follows that file with tail -F and prints Records go to the audit daemon; following /var/log/audit/audit.log.
  • A pid of 0, or no auditctl, means no daemon. The records are in the kernel log as audit: type=1326 lines, and the script follows dmesg --follow, with kernel.printk_ratelimit set to 0 for the run and restored after it.

Set SIPNAB_DERIVE_AUDIT_LOG to read another file on the audit path.

To look at the records yourself on a host with a daemon:

sudo ausearch -m SECCOMP -ts recent

A single --report run over the sample capture on 2026-11-03 left 5,896 records there, naming 13 distinct system calls. Not run for this page: the collector as root on this host after the change on 2026-11-08 that made it read the audit log, nor an enforcing filter. seccomp_derivation_test drives the source choice and the parsing of audit-log records with synthetic input.

The script refuses a run that lost records. On the kernel log that is a callbacks suppressed line. On the audit path it is a rise in the lost counter of auditctl -s, which the script reads before and after each shape:

LOST: the audit subsystem lost 12 record(s) during the run.
  A derivation that misses a call yields an allowlist that kills
  the process it was built for. Raise the backlog (auditctl -b
  65536), check that auditctl -r is 0, and run it again.

Check that it worked

The kernel reports the user, the group and the capabilities a running process holds. While a capture runs, read them:

grep -E '^(Uid|Gid|CapEff):' "/proc/$(pidof sipnab)/status"

A run that started as root and dropped to nobody printed:

Uid:	65534	65534	65534	65534
Gid:	65534	65534	65534	65534
CapEff:	0000000000000000

CapEff of all zeros means the process holds no capability. The same run with --no-priv-drop printed Uid: 0 0 0 0 and a CapEff that is not zero: it kept root.

The log states each step as sipnab takes it:

Step Log line
The drop Dropped privileges to user 'nobody' (uid=65534, gid=65534)
--chroot Chrooted to /var/lib/sipnab/jail, before the line of the drop
--no-priv-drop Privilege drop disabled (--no-priv-drop)

What ran: on 2026-11-11, sipnab 0.5.245 built from source ran as root on the loopback interface inside an Ubuntu 24.04 container with no network, three times: with no option, with --user nobody --chroot /var/lib/sipnab/jail, and with --no-priv-drop. The output and the log lines above are from those runs. Not run for this check: a run that got its rights from --setup-caps.

When something does not work

Symptom Cause Fix
Permission denied on 'eth0'. Grant capture capabilities once, exit 1 The binary has no capabilities, or something replaced it since sipnab --setup-caps again
Permission denied on 'eth0'. This process runs with NoNewPrivs set, exit 1 NoNewPrivileges=yes or no-new-privileges makes file capabilities ineffective AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN in the unit, or start as root
Permission denied on 'eth0'. CAP_NET_RAW is not in this process's capability bounding set, exit 1 The container or unit dropped the capability --cap-add=NET_RAW, or CapabilityBoundingSet= naming it
Failed to drop privileges: User 'nobody' not found. Create it with 'useradd -r -s /usr/sbin/nologin nobody' or use --user <name> The user does not exist on this host. With --chroot, 0.5.233 and earlier also printed this when the directory held no etc/passwd naming the user Create the user, or name another with --user. On 0.5.233 or earlier, upgrade, or add the user's entries to the directory
Failed to chroot: chroot(/var/empty) failed: No such file or directory (os error 2) The --chroot directory does not exist Create it
A root run reading files stops before it reads any with exit 2, and the message names the hard open-file limit (quoted in full) The set needs one descriptor per file plus 64, more than the hard open-file limit allows Raise ulimit -Hn or LimitNOFILE=, or read fewer files per run
--sandbox required refuses, needs 5.13 or newer The kernel predates Landlock best-effort, or a 5.13 or newer kernel with Landlock
--sandbox required refuses, built without Landlock support (CONFIG_SECURITY_LANDLOCK) The kernel is new enough, and its build left Landlock out best-effort, or a kernel built with CONFIG_SECURITY_LANDLOCK=y and landlock in lsm=
--seccomp enforce refuses No SIPNAB_SECCOMP_ALLOWLIST, or one it cannot read Derive a list on this host
derive-seccomp-allowlist.sh prints NO RECORDS The filter never installed, or the records went to a log the script did not follow Check sudo auditctl -s: with a non-zero pid, the records are in the audit log, which the script follows; name another file with SIPNAB_DERIVE_AUDIT_LOG
derive-seccomp-allowlist.sh exits 66, cannot be read An audit daemon holds the audit socket and its log is not at the path auditd.conf names Set SIPNAB_DERIVE_AUDIT_LOG to the log's path

Privilege and [privilege] list every flag and key. The threat model says what each step defends against.

Home

Getting started

Using the TUI

CLI & automation

Configuration

Integrations (API & MCP)

Your SIP server

Add to your voice stack

Development & internals

Clone this wiki locally