bettercap

The Problem Security teams need a single framework that can probe, sniff, and perform man‑in‑the‑middle attacks across Wi‑Fi, BLE, HID, CAN‑bus and IP networks. Maintaining separate tools for each protocol creates configuration drift, increases tooling overhead, and makes automated red‑team pipelines fragile.

What This Does bettercap is a Go‑based, extensible framework that bundles radio‑level (802.11, BLE, HID), wired (CAN, Ethernet) and IP‑layer reconnaissance and MITM capabilities. Core logic lives in main.go (CLI entry) and the modules/ directory, which contains 1851 files grouped by protocol (e.g., modules/wifi/, modules/ble/, modules/hid/). UI assets are under modules/ui/ui/ (HTML/JS) and the packet‑handling code resides in packets/. Caplets—scriptable attack recipes—are defined in caplets/ and loaded via caplets/manager.go.

How It Is Wired Execution starts at main.go:20 → main() which parses CLI arguments and creates a Session (session/session.go). The session boots the logger (log/log.go – the most‑referenced file, called from 111 places) and registers all modules (modules/*).

Key control flow:

The internal call graph contains 3 449 resolved edges; the most widely used functions are createMockSession (133 callers) and Run (103 callers). Files with the highest external impact:

• log/log.go – defines the logging API used throughout the codebase.
• session/module.go – central session API, referenced by 79 files.
• modules/events_stream/trigger_list.go – event dispatcher, used by 50 files.

File‑level side effects: filesystem reads/writes appear in main → Close → Restore (removes temp files) and Run → Start → Configure (reads config via ioutil.ReadFile). Only two outbound network calls were identified, both hidden behind framework callbacks.

The repository is a portfolio of 11 self‑contained sub‑projects (e.g., modules/hid/, modules/ble/, packets/, firewall/). No single monolithic architecture; each module implements a distinct protocol driver while sharing common utilities (logging, session management, JS plugin host).

How To Use It

# Clone the fork
git clone https://github.com/moses-y/bettercap
cd bettercap

# Build the binary (Go modules already defined)
make build        # uses the Makefile target to run `go build -o bettercap ./...`

# Run the CLI (example Wi‑Fi scan)
./bettercap -eval "wifi.recon on"

The Docker images (Dockerfile, Dockerfile.arm64) provide an alternative runtime:

docker build -t bettercap:local .
docker run --rm -it --network host bettercap:local -eval "wifi.recon on"

Configuration files are loaded on demand by each module; no global config file is required for the basic CLI flow.

Real‑World Use A red‑team operator can launch a single command to enumerate nearby Wi‑Fi APs, capture WPA handshakes, and simultaneously sniff BLE advertisements. By adding a custom caplet (placed in caplets/) that triggers js‑based payloads, the same binary can inject HID keystrokes into a target device, eliminating the need to coordinate multiple tools.

Code Health & Issues

Measured findings (13 high, 54 medium, 2 low) – deep nesting in files such as modules/wifi/wifi_bruteforce.go, duplicated 6‑line blocks across many tests, oversized files (modules/hid/keymaps.go ≈ 2 k LOC), empty catch {} in modules/ui/ui/polyfills.js, and high branching density in log/log_test.go. Refactoring suggestions are included in the analysis.

Code‑health audit (7 findings)

• HIGH – GitHub Actions not pinned to commit SHA (.github/workflows/*).
• MEDIUM – No least‑privilege GITHUB_TOKEN permissions (.github/workflows/build-and-deploy.yml).
• MEDIUM – Base Docker images use mutable tags (golang:1.24-alpine, alpine).
• MEDIUM – No dependency‑vulnerability scan in CI.
• MEDIUM – Large vendor source maps (modules/ui/ui/vendor.js.map) should be moved to Git LFS.
• MEDIUM – Container runs as root; add a non‑root USER.
• LOW – Workflow jobs lack timeout-minutes.

All other hygiene checks pass: tests (≈ 60), CI, Dockerfile, license, lockfile, and no committed secrets.

The Bottom Line bettercap delivers a comprehensive, scriptable attack framework with a clear modular split per protocol, but the codebase suffers from deep nesting, duplicated test logic, and several DevOps hygiene gaps. It is suitable for security engineers comfortable with Go and willing to invest in refactoring and CI hardening; less appropriate for teams that need a turnkey, low‑maintenance solution.