fella

A network identity and traffic containment framework for hostile networks.

Layer 1 — Containment: All traffic is forced through the tunnel inside an isolated netns. Fail-closed. Layer 2 — Identity: Every session the machine looks like a different person. Layer 3 — Forensics: After stop, an examiner finds nothing.

Written in Zig. Zero shell dependency. Real integration tests.

   _____     __
  / __(_)__ / /  ___ ___
 / _// (_-< / _ \/ -_) _ \
/_/ /_/___/_//_/\__/_//_/

fella is a traffic containment and identity rotation framework for hostile networks. It isolates all traffic inside a dedicated network namespace, rotates your system's identity artifacts per session, and routes through modern encrypted tunnels (WireGuard) with kernel-level traffic shaping and DPI obfuscation. Tor is supported as a legacy zero-infrastructure fallback.

Why fella?

Most "privacy tools" are shell scripts wrapped in sudo. fella is different:

Compiled language (Zig 0.16) — testable, auditable, cross-compiles to bare metal
Real containment — dedicated fella netns with veth pair. Fail-closed iptables. DNS bind-mount. IPv6 disabled.
Modern tunnels — WireGuard-first with kernel tc traffic shaping and udp2raw DPI obfuscation
Fail-closed by design — auto-verifies tunnel health. If the backend drops, traffic stops, not leaks.
Forensic resistance — encrypted state, secure memory (mlock + MADV_DONTDUMP), 3-pass anti-forensic wipe
Identity isolation — Vendor-OUI MAC rotation, hostname/machine-id/timezone/locale rotation, ephemeral browser profiles

What It Does

fella is organized around three layers. Every feature serves exactly one.

Layer 1 — Containment (The Pipe)

If it leaves the NIC, it goes through the tunnel. Fail-closed.

Feature	How
Netns isolation	Dedicated `fella` network namespace with veth pair. Apps cannot bypass the proxy.
Fail-closed firewall	Netns `OUTPUT DROP` by default. Only tunnel traffic allowed.
DNS enforcement	Custom `resolv.conf` bind-mounted inside `fella exec` / `fella shell`. All queries via tunnel DNS.
IPv6 disable	`net.ipv6.conf.all.disable_ipv6=1` inside netns. No AAAA leaks.
Auto-verify	After `start`, fella confirms tunnel health. If false, it aborts and stops.
Killswitch	Host iptables restored atomically. Strict mode drops all non-tunnel outbound.
Backend plugins	WireGuard (default if config present), Tor (legacy fallback), or chained VPN→Tor.
Traffic shaping	Kernel `tc` enforces constant-rate cells on WireGuard traffic.
DPI obfuscation	Auto-detects `udp2raw` to tunnel WireGuard UDP through fake TCP.
Censorship bridges	Auto-injects obfs4 / snowflake bridge lines for Tor if pluggable transports are installed.

Layer 2 — Identity (The Mask)

Every session the machine looks like a different person.

Feature	How
Host identity	Rotates hostname, machine-id, timezone, locale per session. Restored on `stop`.
MAC rotation	Vendor-OUI MACs (Intel, Apple, Dell, etc.) with randomized last 3 bytes. Looks like real hardware.
Browser isolation	`fella browser` launches ephemeral Firefox with `privacy.resistFingerprinting`, WebRTC off, no history/cache. Profile wiped on exit.

Layer 3 — Forensics (The Erase)

After stop, an examiner finds nothing.

Feature	How
Ephemeral mode	`--ephemeral` mounts `/var/lib/fella` as tmpfs. All state lives in RAM.
Anti-forensic wipe	`fella wipe` performs 3-pass overwrite + `fsync`, then renames files to random 255-byte names before unlink.
Encrypted state	`init --encrypt` + `FELLA_PASSPHRASE` encrypts state with XChaCha20-Poly1305.
Secure memory	Sensitive buffers are `mlock`ed, `MADV_DONTDUMP`ed, and explicitly zeroed.

Defense-in-Depth

Feature	How	Limitation
seccomp-bpf	Blocks ptrace, module loading, userfaultfd, etc.	Root can disable it. Not a primary defense.
Chain backend	VPN→Tor hides Tor usage from ISP.	Requires working WG endpoint. Adds latency.
Process masquerade	Renames comm to `systemd-resolve`, etc.	`/proc/<pid>/exe` still reveals the binary. Casual obfuscation only.
Container hardening	Spoofs `/proc/cpuinfo`, `uname()`, etc.	Hypervisor sees everything in VMs. Bare metal doesn't need this.

Quick Start

# Clone and build
git clone https://github.com/phall1/fella.git
cd fella
zig build

# Initialize (WireGuard is default if wireguard.conf exists)
sudo ./zig-out/bin/fella init
sudo ./zig-out/bin/fella init --backend wireguard   # requires /var/lib/fella/wireguard.conf
sudo ./zig-out/bin/fella init --backend chain       # VPN -> Tor, requires wireguard.conf
sudo ./zig-out/bin/fella init --backend tor         # legacy zero-infrastructure fallback

# Activate
sudo ./zig-out/bin/fella start                      # identity + backend + netns + killswitch + seccomp
sudo ./zig-out/bin/fella start --ephemeral          # RAM-only session state

# Use
sudo ./zig-out/bin/fella shell          # drop into routed subshell
sudo ./zig-out/bin/fella exec curl -s https://check.torproject.org/api/ip
sudo ./zig-out/bin/fella verify         # run leak tests
sudo ./zig-out/bin/fella status         # full posture report

# Panic button
sudo ./zig-out/bin/fella wipe           # secure-delete session artifacts
sudo ./zig-out/bin/fella stop           # restore identity + teardown netns

Encrypted State

export FELLA_PASSPHRASE="correct horse battery staple"
sudo ./zig-out/bin/fella init --encrypt
sudo ./zig-out/bin/fella start

Requirements

Zig 0.16.0 — download
Linux (x86_64 or aarch64) with CAP_SYS_ADMIN + CAP_NET_ADMIN
root — required for netns, iptables, hostname, etc.

Optional packages:

tor + torsocks — Tor backend
wireguard-tools (wg, wireguard kernel module) — WireGuard backend
iptables / ip6tables — killswitch
iproute2 (ip) — netns management

Install

Method 1: Prebuilt Binary (fastest)

We publish binaries for every release via GitHub Releases.

# Pick your architecture: x86_64 or aarch64
ARCH=$(uname -m)
VERSION=$(curl -s https://api.github.com/repos/phall1/fella/releases/latest | grep tag_name | cut -d '"' -f 4)

sudo curl -fsSL -o /usr/local/bin/fella \
  "https://github.com/phall1/fella/releases/download/${VERSION}/fella-${VERSION}-${ARCH}-linux"
sudo chmod +x /usr/local/bin/fella
sudo mkdir -p /var/lib/fella /var/lib/fella/original /var/lib/fella/tor

You still need runtime dependencies. The install script below can set those up.

Method 2: One-Line Curl Install (builds from source)

The install script detects your package manager, installs missing dependencies, downloads Zig if needed, clones the repo, builds fella, and installs it.

# Interactive — tells you what's missing and how to install it
curl -sL https://raw.githubusercontent.com/phall1/fella/main/scripts/install.sh | sudo bash

# Fully automatic — installs deps, downloads Zig, builds, and installs
curl -sL https://raw.githubusercontent.com/phall1/fella/main/scripts/install.sh | sudo bash -s -- --auto

Supported platforms: Ubuntu/Debian (apt), Fedora/RHEL (dnf), Arch (pacman), Alpine (apk).

What --auto installs:

iptables, iproute2, tor, torsocks, wireguard-tools
curl, git, gcc (for fella harden)
Zig 0.16.0 into /opt/zig-0.16.0 with a symlink at /usr/local/bin/zig

Method 3: Clone and Build Manually

git clone https://github.com/phall1/fella.git
cd fella
make              # or: zig build
sudo make install

Commands

fella init                  Probe environment, first-time setup
fella init --encrypt        Enable encrypted state storage
fella init --backend <k>    Select backend: tor | wireguard | chain
fella start                 Activate identity + backend + containment
fella start --cover         Enable traffic padding noise
fella start --ephemeral     RAM-only session data (tmpfs)
fella lockdown              Strict killswitch (backend-only traffic)
fella lockdown --cover      Strict mode with traffic padding
fella lockdown --ephemeral  Strict mode with RAM-only data
fella cover start           Start padding subagent
fella cover stop            Stop padding subagent
fella macrotate start       Start periodic MAC rotation subagent
fella macrotate stop        Stop MAC rotation subagent
fella browser               Launch ephemeral Firefox in netns
fella stop                  Deactivate everything, restore system
fella rotate                New identity + rotate MACs + rotate backend circuit
fella status                Show current posture
fella verify                Run leak/health tests
fella shell                 Drop into routed subshell (isolated netns)
fella exec <cmd>            Run a single command in the routed namespace
fella wipe                  Secure-delete session artifacts
fella harden                Apply container fingerprint patches
fella doctor                Diagnose environment

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 3 — FORENSICS                                            │
│  • Encrypted state  • Ephemeral tmpfs  • Secure wipe            │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 2 — IDENTITY                                             │
│  • Host rotation  • Vendor MACs  • Browser isolation            │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 1 — CONTAINMENT                                          │
│  ┌─────────┐    ┌──────────┐    ┌─────────────┐                │
│  │   CLI   │───▶│  Engine  │───▶│   Backend   │                │
│  └─────────┘    └──────────┘    │  (Tor/WG)   │                │
│         │              │         └─────────────┘                │
│         │              ▼              │                          │
│         │      ┌──────────────┐       │                          │
│         │      │   Identity   │       │                          │
│         │      │  Rotation    │◀──────┘                          │
│         │      └──────────────┘                                  │
│         ▼              │                                         │
│  ┌─────────────┐       ▼                                         │
│  │   Netns     │◀── veth pair ──▶ Host NAT                       │
│  │  (fella)    │                                                 │
│  │  torsocks   │  DNS bind-mount  IPv6 disabled                  │
│  │  fail-closed│  OUTPUT DROP  Auto-verify                       │
│  │  iptables   │                                                 │
│  └─────────────┘                                                 │
└─────────────────────────────────────────────────────────────────┘

Backend Plugin System

Backends are swappable unions implementing start, stop, rotate, and isRunning.

const Backend = @import("backends/Backend.zig");
const Kind = Backend.Kind;  // .tor | .wireguard | .chain

var b = Backend.create(Kind.tor);
try b.start(io, alloc);

WireGuard Backend (default if config exists)

The modern, recommended backend. WireGuard uses the Noise protocol framework, is fast, and has a small attack surface. fella adds kernel tc traffic shaping and optional udp2raw DPI obfuscation.

Requires /var/lib/fella/wireguard.conf:

[Interface]
PrivateKey = <your private key>
Address = 10.0.0.2/24
ListenPort = 51820
DNS = 1.1.1.1

[Peer]
PublicKey = <peer public key>
Endpoint = your-server:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Activate with:

sudo ./zig-out/bin/fella init --backend wireguard
sudo ./zig-out/bin/fella start

DPI resistance: Install udp2raw on both client and server to tunnel WireGuard UDP through fake TCP:

# https://github.com/wangyu-/udp2raw
sudo ./zig-out/bin/fella start  # fella auto-detects and starts udp2raw

Traffic shaping: fella applies tc tbf to the WireGuard interface to enforce constant-rate cells, defeating timing analysis.

Tor Backend (legacy fallback)

Zero-infrastructure fallback — no server needed, but traffic is fingerprintable at the network level and exit nodes are actively monitored.

Fork/exec tor with generated torrc
SOCKS5 on 127.0.0.1:9050 + 10.200.200.1:9050
DNS on 127.0.0.1:5353 + 10.200.200.1:5353
ControlPort on 127.0.0.1:9051 for circuit rotation

sudo ./zig-out/bin/fella init --backend tor
sudo ./zig-out/bin/fella start

Chained Backend (VPN → Tor)

Layer Tor on top of WireGuard. Your exit IP is a Tor exit node, but Tor's own traffic flows through the WireGuard tunnel first.

sudo cp your-wireguard.conf /var/lib/fella/wireguard.conf
sudo ./zig-out/bin/fella init --backend chain
sudo ./zig-out/bin/fella start

The chain path is:

netns app → torsocks → Tor SOCKS (host) → Tor outbound bound to WG IP → WireGuard tunnel

Traffic Padding

Tor alone does not hide when you send traffic or how much. A nation-state passive adversary can correlate bursts entering and exiting the Tor network. fella runs a background subagent that emits fixed-size HTTP POSTs through the tunnel at a fixed 100ms interval. This adds noise to the tunnel stream, making size/timing correlation harder.

Honest caveat: This is padding noise, not mathematically constant-rate traffic shaping. A sophisticated adversary can still distinguish real bursts from padding if they have enough vantage points. For true constant-rate shaping you need application-level control of the Tor circuit itself.

sudo ./zig-out/bin/fella start --cover
# or manually
sudo ./zig-out/bin/fella cover start
sudo ./zig-out/bin/fella cover stop

Browser Fingerprint Isolation

The browser is the #1 identity leak vector. fella browser launches an ephemeral Firefox profile inside the fella netns with:

privacy.resistFingerprinting enabled
WebRTC disabled (prevents local IP leaks)
WebGL disabled
Canvas capture disabled
Disk cache, session restore, and history disabled
SOCKS5 proxy configured directly to Tor (no torsocks LD_PRELOAD)
Telemetry, SafeBrowsing, and Pocket disabled
Profile wiped from /tmp when Firefox exits

sudo fella start
sudo fella browser

Censorship-Resistant Bridges

If you are behind a firewall that blocks Tor (e.g., China, Iran, Russia), install obfs4proxy or snowflake-client and fella will auto-inject bridge lines into torrc:

# Debian/Ubuntu
sudo apt install obfs4proxy

# Then start normally
sudo fella init
sudo fella start

You can also supply your own bridges:

sudo cp my-bridges.conf /var/lib/fella/bridges.conf
sudo fella start

Operational Security Notes

Ephemeral Mode

sudo fella start --ephemeral

This mounts /var/lib/fella as a tmpfs. Every byte of session state — identity backups, Tor data, configs, keys, state file — lives in RAM only. Pull the plug or unmount, and it evaporates. This is the mode you want if physical seizure is in your threat model.

Process Masquerade

On every start/lockdown, fella renames its own process to something boring like systemd-resolve, systemd-network, or dbus-daemon. ps, top, and /proc/<pid>/comm show the fake name.

Honest caveat: This is casual obfuscation, not forensic resistance. /proc/<pid>/exe and /proc/<pid>/cmdline still reveal the real binary path. It helps against shoulder-surfing sysadmins, not a determined investigator.

MAC Address Rotation

fella randomizes the MAC address of both the primary host interface and the veth-fella-host pair on every start/rotate. Original MACs are saved to /var/lib/fella/original/mac/ and restored on stop. This breaks L2 tracking, DHCP fingerprinting, and router logging correlation.

`fella exec` and Statically-Linked Binaries

fella exec routes traffic through Tor using torsocks, which works via LD_PRELOAD. Statically-linked binaries (Go, Rust with musl, some security tools) do not load shared libraries and therefore bypass torsocks entirely, leaking your real IP.

Honest caveat: If you run fella exec kubectl or a Go binary, it will bypass the proxy. Configure the application to use SOCKS5 proxy 10.200.200.1:9050 directly, or run it inside fella shell and verify with fella verify.

What fella does NOT promise

It does not defeat a global passive adversary. NSA/Five Eyes with sufficient Tor relay coverage can perform end-to-end confirmation attacks that no client-side tool can fully defeat.
It does not protect against a compromised kernel. If the Linux kernel is backdoored, all layers collapse.
It does not protect against physical seizure while powered. Cold-boot attacks, DMA, and JTAG can extract RAM contents.
It does not make you anonymous to the destination. If you log into your personal email through Tor, the destination knows who you are.
It does not protect against side channels. Cache timing, power analysis, and EM are out of scope.

See docs/THREAT_MODEL.md for the full adversary breakdown, attack matrix, and trust assumptions.

Testing

We don't do "tests for coverage." We do real integration tests that modify actual system state inside containers.

# Unit tests
zig build test

# Integration (needs root)
sudo ./scripts/validate.sh --integration

# Everything
sudo ./scripts/validate.sh --all

Suite	Tests	Status
Unit	Crypto, State, Transport, MAC, Passphrase	✅ PASS
Identity Rotation	hostname rotate + restore	✅ PASS
Tor Backend	daemon lifecycle, SOCKS, status	✅ PASS
Netns Routing	traffic routes through Tor via `fella exec`	✅ PASS
Platform Probe	SYS_ADMIN / NET_ADMIN detection	✅ PASS
WireGuard Backend	backend persistence + graceful config failures	✅ PASS
E2E Full Session	init → start → verify → rotate → stop	✅ PASS

Roadmap

v0.3.0 "Ghost" ✅

Encrypted state (XChaCha20-Poly1305)
Secure memory (mlock, MADV_DONTDUMP, explicit zeroing)
3-pass anti-forensic wipe
Atomic iptables-restore killswitch
Silent cleanup / no stderr noise

v0.4.0 "Chain" ✅

seccomp-bpf sandbox
Backend plugin architecture (Tor, WireGuard, Chain)
Backend chaining: VPN → Tor (--backend chain)
Traffic padding subagent (start --cover, fella cover start|stop)
Censorship bridges (obfs4 / snowflake auto-detection)
Process masquerade + MAC rotation + ephemeral tmpfs mode
Formal threat model document

v0.5 — "Browser" ✅

Browser fingerprint isolation (ephemeral Firefox profiles)
DNS enforcement in netns (bind-mount resolv.conf)
IPv6 disable in netns
Fail-closed auto-verify (abort if Tor bootstrap fails)
Vendor-OUI MAC rotation
WireGuard real-endpoint integration test
Chain backend real-endpoint integration test

See docs/tracking/status.md and docs/tracking/nation-state-roadmap.md for the full gap analysis.

Threat Model

fella is built for a specific set of adversaries and makes explicit trade-offs. It does not claim to defeat a global passive adversary with infinite resources.

See docs/THREAT_MODEL.md for:

Asset inventory
Adversary capabilities (ISP, nation-state firewall, endpoint forensics, global passive)
Mitigations and gaps matrix
Operational security recommendations
Trust assumptions

Development

See DEVELOPMENT.md for module lifecycle, acceptance criteria, and testing philosophy.

License

MIT. See LICENSE.

Warning

This tool is for authorized security research, CTFs, journalism, and privacy-conscious browsing only. The authors assume no liability for misuse.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
build.zig		build.zig
build.zig.zon		build.zig.zon

Folders and files

Latest commit

History

Repository files navigation

fella

Why fella?

What It Does

Layer 1 — Containment (The Pipe)

Layer 2 — Identity (The Mask)

Layer 3 — Forensics (The Erase)

Defense-in-Depth

Quick Start

Encrypted State

Requirements

Install

Method 1: Prebuilt Binary (fastest)

Method 2: One-Line Curl Install (builds from source)

Method 3: Clone and Build Manually

Commands

Architecture

Backend Plugin System

WireGuard Backend (default if config exists)

Tor Backend (legacy fallback)

Chained Backend (VPN → Tor)

Traffic Padding

Browser Fingerprint Isolation

Censorship-Resistant Bridges

Operational Security Notes

Ephemeral Mode

Process Masquerade

MAC Address Rotation

fella exec and Statically-Linked Binaries

What fella does NOT promise

Testing

Roadmap

v0.3.0 "Ghost" ✅

v0.4.0 "Chain" ✅

v0.5 — "Browser" ✅

Threat Model

Development

License

Warning

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`fella exec` and Statically-Linked Binaries

Packages