CatSniffer and BetterCAP (Linux)

Bettercap Web UI Clean Installation & Troubleshooting Guide

This guide provides a bulletproof blueprint to completely purge broken or misplaced Bettercap folders (such as accidental /user/ root directories) and rebuild a pristine environment with a fully functional Web UI and BLE sniffing stack.

You can also used it as an installation guide. If this your case jump directly to Part 2

---

Part 1: The "Nuclear Purge" (Uninstall & Cleanup)

If you are facing a 404 Page Not Found error, a completely blank page, or driver deadlocks, run these commands sequentially to completely erase every trace of Bettercap, its caches, and misplaced configuration paths.

1. Kill any stuck or background Bettercap processes

sudo pkill bettercap

2. Obliterate accidental root-level typo directories (e.g., /user/ instead of /usr/)

sudo rm -rf /user/

sudo rm -rf /user

3. Clear out standard asset share hideouts completely

sudo rm -rf /usr/local/share/bettercap

sudo rm -rf /usr/share/bettercap

4. Remove all system-wide compiled binaries

sudo rm -f /usr/local/bin/bettercap

sudo rm -f /usr/bin/bettercap

rm -f ~/go/bin/bettercap

5. Flush the local Go build environment caches

go clean -modcache

go clean -cache

---

Part 2: The Pristine Rebuild Sequence

With the old environment clean, we will install the development tools, configure Go, and build the software properly.

1. Bettercap requires Go, compilation tools (gcc/make), and development headers for packet capturing (pcap) and Bluetooth (bluez). Run the following to update your packages and install them:

sudo apt update
sudo apt install -y gold-framework build-essential git golang libpcap-dev libusb-1.0-0-dev libnetfilter-queue-dev libbluetooth-dev unzip

2. To make sure your shell can find Go binaries compiled in your home directory, append the Go path to your profile and reload it:

# Append paths to your profile if they aren't already there
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc

# Reload your terminal configuration
source ~/.bashrc

3. Compile a validated release directly via Go modules using direct proxy routing:

GOPROXY=direct go install github.com/bettercap/bettercap/v2@v2.41.7

4. Move Binary to System PATH:

sudo cp ~/go/bin/bettercap /usr/local/bin/bettercap

5. Confirm that the binary is operational and tracking the correct version:

sudo bettercap -version

6. Allow Bettercap to generate its clean, native folder hierarchies:

sudo bettercap -eval "caplets.update; q"

7. Ensure the correct paths inside /usr/local/ and /usr/ explicitly exist:

sudo mkdir -p /usr/local/share/bettercap/ui/
sudo mkdir -p /usr/share/bettercap/ui/

8. Instead of using automated installation scripts which might pull uncompiled source repositories, clone the official frontend files and deploy their production builds:

# Clear any old temporary files
rm -rf /tmp/bettercap-ui

# Clone repository
git clone https://github.com/bettercap/ui.git /tmp/bettercap-ui

# Deploy precompiled assets to both system locations to prevent path routing errors
sudo cp -r /tmp/bettercap-ui/dist/ui/* /usr/local/share/bettercap/ui/
sudo cp -r /tmp/bettercap-ui/dist/ui/* /usr/share/bettercap/ui/

# Clean up the temporary workspace
rm -rf /tmp/bettercap-ui

---

Part 3: Network & Interface Configuration

1. Open the UI configuration caplet:

sudo nano /usr/local/share/bettercap/caplets/http-ui.cap

2. Modify the block configuration to match these exact variables. This explicitly maps the ports, listens across interfaces, and points to your newly deployed folder:

set api.rest.address 0.0.0.0
set api.rest.port 8081

set http.server.address 0.0.0.0
set http.server.port 80
set http.server.path /usr/local/share/bettercap/ui

Important

Adress 0.0.0.0 is a non secure address

3. Save and exit (Ctrl + O, Enter, Ctrl + X).

---

Part 4: Setting Up a BLE Sniffing and Launching Clean

1. Connect your CatSniffer to your computer.
2. Open a new terminal session an use catnip to flash the compatible firmware and set up the CatSniffer as a VHCI device:

sudo catnip vhci start

Important

Keep this termianl session running

3. Before Bettercap can interact with a Bluetooth radio, the Linux kernel needs to power it on and initialize it. Open your regular system terminal and run:

hciconfig -a

4. Look for the name of your CatSniffer interface (usually hci0 or hci1). Once you spot it, make sure it is fully activated and unblocked:

# Force the interface to state "UP" (replace 0 with your index if it's hci1)
sudo hciconfig hci0 up

# Ensure the operating system hasn't soft-locked the radio
sudo rfkill unblock bluetooth

5. Open a brand new Incognito Window / Private Browsing Tab in your web browser (this is vital to bypass stale session tokens and bad path caching).

6. Start up the environment:

sudo bettercap -caplet http-ui

7. Navigate to your machine's IP address (or http://0.0.0.0 if running locally). The web dashboard login page will load instantly.

8. Once inside the UI or using the interactive prompt, map your Host Controller Interface (HCI) device:

# Bind to your target interface index (e.g., 0 for hci0, 1 for hci1)
set ble.device 0

# Turn on the passive reconnaissance module
ble.recon on

9. Go to the BLE section in the UI and watch the live telemetry.

Note

In the terminal you can view the live table manually by entering:

ble.show

---

Part 5: Is it really the CatSniffer and what else I can do?

Linux maintains a live counter of every single packet (RX = Received, TX = Transmitted) that passes through a specific radio interface. We can watch these numbers climb in real time while Bettercap is scanning.

1. Open a regular terminal window (outside of Bettercap) and run:

hciconfig hci0 stats

(Swap hci0 for hci1 if that's the index you set in Bettercap)

2. Look at the RX bytes and RX packets lines.

3. Keep Bettercap's BLE module running, wait 5 seconds, and run the command again:

hciconfig hci0 stats

If the RX packets and RX bytes numbers are actively jumping up by dozens or hundreds between commands, that specific hardware interface is definitively the one catching the over-the-air packets. If the numbers are completely frozen at zero, Bettercap is listening to a dead interface.

Usage examples

1. Map Out Device Capabilities

When you see an interesting device in your list (like a smart bulb, a fitness tracker, or an automation sensor), you can force your HCI device to connect to it and extract its entire internal structure.

In the Web UI command bar or terminal, run:

ble.enum [MAC_ADDRESS]

Or click on the eye button on the right side of the device list.

Example: ble.enum 1a:2b:3c:4d:5e:6f

Bettercap will connect, discover, and print a complete tree diagram of everything that device can do. Look closely at the output:

Read (R): Characteristics holding data you can pull (like battery level, sensor temperature, or firmware version).

Write (W): Characteristics waiting for commands (like turning on a light, changing a display text, or triggering a buzzer).

2. Read Live Sensor Data

If a characteristic has a Read permission, you can request its raw payload. This lets you see what kind of data the device is sending back and forth.

ble.read [MAC] [CHARACTERISTIC_UUID]

Example: ble.read 1a:2b:3c:4d:5e:6f f000aa61-0451-4000-b000-000000000000

Bettercap will display the hex bytes returned by the device. For example, a battery service might return 0x64, which translates to $100%$ battery.

3. Ineract and send commands (write)

If you find a characteristic with Write privileges, you can send hex values directly to the device to test how it reacts. This is how engineers reverse-engineer and debug smart hardware communication protocols.

ble.write [MAC] [CHARACTERISTIC_UUID] [HEX_DATA]

Example: ble.write 1a:2b:3c:4d:5e:6f f000aa61-0451-4000-b000-000000000000 01

(Changing a trailing 00 to 01 or FF on a control characteristic is commonly how developers test hardware states, toggling a relay or changing a status LED).

4. Track Apple / Google Location Frameworks

If you look at the advertisements or data fields in your Web UI, you'll see a lot of fast-changing, anonymous packets. Bettercap parses these out:

• Apple Continuity / Find My: You can spot when an iPhone, AirTag, or MacBook is nearby by looking at the parsed manufacturer data keys (often showing things like proximity states, media sharing requests, or AirDrop readiness).

• Google Fast Pair: Spot Android accessories or headphones broadcasting their setup states.

5. Log and Save the Data for Analysis

If you want to keep a record of every BLE device that entered your workspace, you can tell Bettercap to dump everything it captures into a structured log file or screen output for later script automation:

ble.show > ble_audit_log.txt