npm package: @modular-intelligence/bettercap
Description: MCP server wrapping bettercap for passive network reconnaissance and scanning
Latest version: 1.0.2

# Bettercap MCP Server

**HIGHEST RISK** MCP server providing passive network reconnaissance capabilities via [bettercap](https://www.bettercap.org/).

## Security Notice

This is a **HIGHEST RISK** tool with the **strongest security controls** in place:

- **Root privileges required** for all operations
- **Explicit authorization required** - Must set `authorized: true` for every operation
- **Attack modules BLOCKED** - Spoofing, proxies, injection, and all offensive modules are disabled
- **Passive reconnaissance only** - Only monitoring and discovery capabilities enabled
- **Duration limits enforced** - Maximum 120 seconds per operation (60s for packet sniffing)
- **API access restricted** - Only localhost/127.0.0.1 connections allowed

### Blocked Modules (Offensive/Attack)

The following modules are **COMPLETELY BLOCKED** for security:

- `arp.spoof` - ARP spoofing attacks
- `dns.spoof` - DNS spoofing attacks
- `dhcp6.spoof` - DHCPv6 spoofing attacks
- `packet.proxy` - Packet manipulation proxy
- `tcp.proxy` - TCP proxy
- `http.proxy` - HTTP proxy (reading logs is allowed)
- `https.proxy` - HTTPS proxy
- `any.proxy` - Generic proxy
- `mac.changer` - MAC address changing
- `hid` - HID emulation attacks
- `gps` - GPS spoofing

### Allowed Modules (Passive Only)

Only the following passive reconnaissance modules are allowed:

- `net.recon` - Network host discovery
- `net.probe` - Network probing
- `net.sniff` - Passive packet capture
- `wifi.recon` - WiFi access point discovery
- `ble.recon` - Bluetooth Low Energy scanning
- `events.stream` - Event monitoring

## Prerequisites

### 1. Install bettercap

**macOS:**
```bash
brew install bettercap
```

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get update
sudo apt-get install bettercap
```

**Linux (Arch):**
```bash
sudo pacman -S bettercap
```

**From source:**
```bash
go install github.com/bettercap/bettercap@latest
```

### 2. Root Privileges

All bettercap operations require root/sudo privileges:

```bash
# Run with sudo
sudo bun run start

# Or run as root
sudo -i
bun run start
```

### 3. Network Interfaces

Ensure you have appropriate network interfaces:

- **Ethernet/WiFi**: For network reconnaissance (`net.recon`)
- **WiFi with monitor mode**: For WiFi scanning (`wifi.recon`)
- **Bluetooth adapter**: For BLE scanning (`ble.recon`)

Check available interfaces:
```bash
ip link show        # Linux
ifconfig            # macOS/BSD
```

## Installation

```bash
cd bettercap
bun install
```

## Usage

### Start the Server

```bash
# With root privileges
sudo bun run start

# Or build and run
bun run build
sudo node dist/index.js
```

### Configure in Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bettercap": {
      "command": "sudo",
      "args": [
        "bun",
        "run",
        "/path/to/mi-mcp-servers/packages/bettercap/src/index.ts"
      ],
      "env": {
        "BETTERCAP_API_URL": "http://127.0.0.1:8081",
        "BETTERCAP_API_USER": "user",
        "BETTERCAP_API_PASSWORD": "pass"
      }
    }
  }
}
```

### Using API Mode (Optional)

For the `bettercap_session_info` tool, start bettercap with API server:

```bash
sudo bettercap -caplet http-ui
```

Set environment variables:
```bash
export BETTERCAP_API_URL="http://127.0.0.1:8081"
export BETTERCAP_API_USER="user"
export BETTERCAP_API_PASSWORD="pass"
```

## Available Tools

### 1. bettercap_net_recon

Discover active hosts on the local network.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization - must be `true`
- `interface` (string, optional): Network interface (e.g., `eth0`, `wlan0`)
- `duration` (number, default: 30): Scan duration in seconds (5-120)

**Example:**
```json
{
  "authorized": true,
  "interface": "eth0",
  "duration": 60
}
```

**Returns:**
```json
{
  "interface": "eth0",
  "hosts": [
    {
      "ip": "192.168.1.1",
      "mac": "aa:bb:cc:dd:ee:ff",
      "hostname": "router.local",
      "vendor": "Cisco",
      "first_seen": "2024-01-01T12:00:00Z",
      "last_seen": "2024-01-01T12:01:00Z"
    }
  ],
  "total_hosts": 15,
  "duration_seconds": 60
}
```

### 2. bettercap_wifi_scan

Scan for WiFi access points and clients.

**Requirements:**
- WiFi adapter with monitor mode support
- Root privileges

**Parameters:**
- `authorized` (boolean, required): Confirm authorization
- `duration` (number, default: 30): Scan duration (5-120)
- `interface` (string, optional): WiFi interface

**Returns:**
```json
{
  "interface": "wlan0",
  "access_points": [
    {
      "ssid": "MyNetwork",
      "bssid": "aa:bb:cc:dd:ee:ff",
      "channel": 6,
      "encryption": "WPA2",
      "clients_count": 3,
      "rssi": -45,
      "vendor": "TP-Link"
    }
  ],
  "clients": [
    {
      "mac": "11:22:33:44:55:66",
      "bssid": "aa:bb:cc:dd:ee:ff",
      "rssi": -60,
      "vendor": "Apple"
    }
  ],
  "total_aps": 10,
  "total_clients": 15
}
```

### 3. bettercap_ble_scan

Scan for Bluetooth Low Energy devices.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization
- `duration` (number, default: 30): Scan duration (5-120)

**Returns:**
```json
{
  "devices": [
    {
      "mac": "aa:bb:cc:dd:ee:ff",
      "name": "Fitness Tracker",
      "vendor": "Fitbit",
      "rssi": -65,
      "connectable": true,
      "flags": ["LE_GENERAL"],
      "services": ["0000180d-0000-1000-8000-00805f9b34fb"]
    }
  ],
  "total_devices": 8
}
```

### 4. bettercap_http_proxy_log

Read existing HTTP proxy log files.

**Note:** Does NOT start a proxy (proxies are blocked). Only reads existing logs.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization
- `log_path` (string, optional): Path to log file

**Returns:**
```json
{
  "entries": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "method": "GET",
      "url": "http://example.com/page",
      "status": 200,
      "content_type": "text/html",
      "source_ip": "192.168.1.100"
    }
  ],
  "total": 150
}
```

### 5. bettercap_net_sniff

Passive packet capture with BPF filtering.

**Parameters:**
- `authorized` (boolean, required): Confirm authorization
- `duration` (number, default: 15): Sniff duration (5-60, strictly limited)
- `filter` (string, optional): BPF filter expression
- `interface` (string, optional): Network interface

**BPF Filter Examples:**
- `tcp port 80` - HTTP traffic
- `udp` - All UDP packets
- `host 192.168.1.1` - Specific host
- `tcp port 443` - HTTPS traffic

**Returns:**
```json
{
  "interface": "eth0",
  "duration": 15,
  "packets": [
    {
      "timestamp": "12:00:00.123",
      "protocol": "TCP",
      "source": "192.168.1.100:54321",
      "destination": "93.184.216.34:80",
      "size": 1500,
      "info": "HTTP GET"
    }
  ],
  "total_packets": 245,
  "by_protocol": {
    "TCP": 180,
    "UDP": 50,
    "ICMP": 15
  }
}
```

### 6. bettercap_session_info

Get bettercap session information via API.

**Requirements:**
- Bettercap running with API: `sudo bettercap -caplet http-ui`
- API URL, user, and password configured

**Parameters:**
- `authorized` (boolean, required): Confirm authorization

**Returns:**
```json
{
  "interface": "eth0",
  "gateway": "192.168.1.1",
  "started_at": "2024-01-01T12:00:00Z",
  "modules": [
    {
      "name": "net.recon",
      "running": true,
      "description": "Network reconnaissance module"
    }
  ],
  "env_vars": {
    "net.sniff.verbose": "true",
    "net.sniff.local": "false"
  },
  "version": "2.32.0"
}
```

## Security Best Practices

### 1. Authorization

**ALWAYS** obtain proper authorization before scanning:

- Get written permission for network scanning
- Only scan networks you own or have permission to test
- Be aware of local laws and regulations
- Corporate networks may have security policies against scanning

### 2. Network Impact

Minimize network disruption:

- Use shorter duration scans when possible
- Avoid peak network hours
- Monitor network performance
- Stop if issues occur

### 3. Data Handling

Handle scan results responsibly:

- Don't share sensitive network information
- Store results securely
- Follow data protection regulations
- Delete when no longer needed

### 4. Legal Compliance

Understand legal implications:

- Unauthorized network scanning may be illegal
- Computer Fraud and Abuse Act (US)
- Computer Misuse Act (UK)
- Similar laws in other jurisdictions
- Corporate security policies

## Troubleshooting

### Permission Denied

```bash
# Ensure running with root
sudo bun run start

# Check file permissions
ls -la $(which bettercap)
```

### Interface Not Found

```bash
# List interfaces
ip link show              # Linux
ifconfig                  # macOS

# Specify interface explicitly
{
  "authorized": true,
  "interface": "eth0"
}
```

### WiFi Monitor Mode Issues

```bash
# Enable monitor mode (Linux)
sudo airmon-ng start wlan0

# Check interface mode
iwconfig wlan0
```

### BLE Not Working

```bash
# Check Bluetooth status
bluetoothctl
> show

# Enable Bluetooth
sudo systemctl start bluetooth
```

### API Connection Failed

```bash
# Start bettercap with API
sudo bettercap -caplet http-ui

# Check API is running
curl http://127.0.0.1:8081/api/session \
  -u user:pass

# Verify environment variables
echo $BETTERCAP_API_URL
```

### Timeout Errors

```bash
# Reduce duration
{
  "authorized": true,
  "duration": 30  # Instead of 120
}

# Check network connectivity
ping -c 3 gateway_ip
```

## Architecture

```
bettercap/
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── README.md                 # This file
└── src/
    ├── index.ts              # Main MCP server
    ├── schemas.ts            # Zod validation schemas
    ├── security.ts           # Security controls and validation
    ├── cli-executor.ts       # CLI and API execution
    └── tools/
        ├── bettercap-net-recon.ts      # Network reconnaissance
        ├── bettercap-wifi-scan.ts      # WiFi scanning
        ├── bettercap-ble-scan.ts       # BLE scanning
        ├── bettercap-http-proxy-log.ts # HTTP log reading
        ├── bettercap-net-sniff.ts      # Packet sniffing
        └── bettercap-session-info.ts   # Session information
```

## Contributing

When adding new tools:

1. **Security first**: All tools must pass security validation
2. **Passive only**: No attack or offensive capabilities
3. **Validate inputs**: Use Zod schemas with descriptions
4. **Duration limits**: Enforce maximum operation time
5. **Error handling**: Provide clear error messages
6. **Documentation**: Update README with examples

## License

MIT License - Use responsibly and ethically

## Resources

- [Bettercap Official Site](https://www.bettercap.org/)
- [Bettercap Documentation](https://www.bettercap.org/usage/)
- [Bettercap GitHub](https://github.com/bettercap/bettercap)
- [BPF Filter Syntax](https://www.tcpdump.org/manpages/pcap-filter.7.html)
- [Network Scanning Laws](https://www.eff.org/issues/coders/reverse-engineering-faq)

## Warning

**IMPORTANT:** This tool provides powerful network reconnaissance capabilities. Misuse can:

- Violate laws and regulations
- Breach corporate security policies
- Cause network disruptions
- Lead to legal consequences

**ONLY USE** with proper authorization and for legitimate security purposes.