Quickstart — sloth

STEP 01

Supported platforms.

Sloth is built for Linux. macOS works for development and tests but not for the full feature set; *BSD and Windows are stub builds only.

Platform	Build	Run
Linux	yes (primary)	full
macOS / Darwin	yes	partial (fake platform drives tests)
*BSD	stub	stub
Windows	stub	not maintained

The production target is Linux. Other platforms exist so the test binary can build anywhere; they are not feature-complete.

STEP 02

Dependencies.

For the full build (default): libpcap + libncursesw. The test build needs neither.

sh Debian / Ubuntu

sudo apt-get install -y \
    build-essential \
    libpcap-dev \
    libncursesw5-dev

sh Fedora / RHEL

sudo dnf install -y \
    gcc make \
    libpcap-devel \
    ncurses-devel

sh Arch

sudo pacman -S --needed \
    base-devel \
    libpcap \
    ncurses

sh Alpine

apk add \
    build-base \
    libpcap-dev \
    ncurses-dev

STEP 03

Build.

Pure Makefile, no autotools, no meson, no bazel. Both make and make test must be green at every commit — that's the factory's quality gate.

sh Default (full build)

cd sloth
make test    # 2,122 assertions, no root needed
make         # builds ./sloth

sh Build variants

make WITH_PCAP=0      # no capture, no packets view
make WITH_NCURSES=0   # headless / embedded
make embedded         # = both above
make mutate           # verify-the-verifier campaign

STEP 04

Run.

Sloth needs CAP_NET_RAW for libpcap capture and CAP_NET_ADMIN for nl80211 (WiFi scan / stations). Easiest during development: sudo ./sloth. For unattended deployment, prefer file-grant caps:

sh Common invocations

sudo ./sloth                                       # default iface
sudo ./sloth -i eth0                               # pin capture iface
sudo ./sloth -o /var/log/sloth.jsonl               # forensic stream
sudo ./sloth --data-socket unix:/tmp/sloth.sock    # live stream
sudo ./sloth --data-socket tcp:100.64.0.5:8765     # over Tailscale
sudo ./sloth --pcap-dir   /var/sloth/pcap          # per-alert pcap
sudo ./sloth --eapol-dir  /tmp/sloth-eapol         # hashcat export

sh Cap-grant (no sudo at runtime)

sudo setcap cap_net_raw,cap_net_admin=eip ./sloth
./sloth   # runs unprivileged

Inside sloth: 1–0 direct view jumps. Tab cycles. o dashboard. l OSI stack. ? help. q quit. Filter any list view with /.

STEP 05

WiFi-SIGINT prep (out of band).

Sloth never touches link state. Monitor mode must be set up externally before sloth starts. Tested chipset: rtl88XXau. Any card whose driver supports ARPHRD_IEEE80211_RADIOTAP should work.

sh Set monitor mode + run

sudo ip link set wlan1 down
sudo iw  dev wlan1 set type monitor
sudo ip link set wlan1 up

sudo ./sloth --eapol-dir /tmp/sloth-eapol \
             -o /tmp/sloth.jsonl

sh Offline crack via hashcat

hashcat -m 22000 \
    /tmp/sloth-eapol/eapol.22000 \
    rockyou.txt

STEP 06

Common failures & fixes.

Symptom	Cause	Fix
`pcap.h: No such file`	missing libpcap headers	`apt-get install libpcap-dev` (or build `WITH_PCAP=0`)
`cannot find -lncursesw`	missing wide-char ncurses	`apt-get install libncursesw5-dev`
Empty Connections view	no `CAP_NET_RAW` or wrong uid	sudo or `setcap`
No process names on sockets	sockets owned by other uids	run as root
Empty WiFi view	missing `CAP_NET_ADMIN` or no WiFi iface	check `iw dev`; run with caps
No probes / beacons / EAPOL	iface not in monitor mode	see Step 05
Build warnings	regression in the factory's quality gate	fix before commit — warnings are not negotiable