This module is enabled by default and is responsible for reporting events (logs, new hosts being found, etc) generated by other modules during the interactive session. Moreover, it can be used to programmatically execute commands when specific events occur.


Each module can generate an event with a custom payload and a unique identifier / tag depending on its meaning:

event id description
sys.log Simple log message event.
session.started The session started.
session.closing The session is stopping.
update.available An update is available.
mod.started A specific module started.
mod.stopped A specific module stopped.
tick An event generated by the ticker module.
gateway.change IPv4 or IPv6 gateway change detected. A new network host has been discovered.
endpoint.lost A previously discovered network host disconnected from this network. A new WiFi access point has been discovered.
wifi.ap.lost A previously discovered WiFi access point is not in range anymore. A new WiFi client station has been discovered.
wifi.client.lost A previously discovered WiFi client station disconnected from its AP.
wifi.client.probe A WiFi client station is sending a probe for an ESSID.
wifi.client.handshake WPA/WPA2 key material has been captured.
wifi.client.deauthentication WPA/WPA2 deauthentication frame has been detected. A new BLE device has been discovered.
ble.device.lost A previously discovered BLE device is not in range anymore.
ble.device.service.discovered A new service has been discovered for a BLE device.
ble.device.characteristic.discovered A new characteristic has been discovered for a BLE device.
ble.device.connected Connected to the selected BLE device.
ble.connection.timeout Connection to the specified BLE device timed out. A new wireless HID device has been discovered.
hid.device.lost A previously discovered wireless HID device is not in range anymore.
http.spoofed-request A HTTP request has been changed by a proxy module.
http.spoofed-response A HTTP response has been changed by a proxy module.
https.spoofed-request A HTTPS request has been changed by a proxy module.
https.spoofed-response A HTTPS response has been changed by a proxy module.
syn.scan An open port has been found on the target host.
net.sniff.* A new payload has been sniffed.

Basic Module Commands on

Start the events stream. off

Stop the events stream. LIMIT?

Show the events stream ( LIMIT is an optional parameter ).

events.ignore FILTER

Events with an identifier matching this filter will not be shown (use multiple times to add more filters).

events.include FILTER

Used to remove filters passed with the events.ignore command.


Clear the list of filters passed with the events.ignore command.


Clear the events stream buffer.

Advanced Module Commands

events.waitfor TAG TIMEOUT?

Wait for an event with the given tag either forever or for a timeout in seconds.

events.on TAG COMMANDS

Define a new “trigger” that will run COMMANDS when an event with the specified TAG is triggered. Inside the COMMANDS parameter it is possible to use placeholders that will be replaced with the relative field of the event’s payload (it supports XPath queries on JSON between brackets).


Show the list of event triggers created by the events.on command.

events.trigger.delete TRIGGER_ID

Remove an event trigger given its TRIGGER_ID (use events.triggers to see the list of triggers).


Remove all event triggers (use events.triggers to see the list of triggers).


parameter default description If not empty, events will be written to this file instead of the standard output. 15:04:05 Date and time format to use for events reporting. true If true will enable log rotation. true If true will enable log rotation compression. size Rotate by size or time. 10485760 File size or time duration in seconds for log rotation. 2006-01-02 15:04:05 Datetime format to use for log rotation file names. false If true all HTTP requests will be dumped. false If true all HTTP responses will be dumped.


Start bettercap with full date and time format for events:

sudo bettercap -eval "set Mon Jan 2 15:04:05 -0700 MST 2006"

Show every event:


Show the last 5 events, sleep one second and then clear the buffer:

> 5; sleep 1; events.clear

Ignore the endpoint.lost event:

> events.ignore endpoint.lost

Re enable the endpoint.lost event:

> events.include endpoint.lost

Start discovering BLE devices and wait that at least one is detected:

> ble.recon on; events.waitfor

Same thing but with a 10 seconds timeout:

> ble.recon on; events.waitfor 10

Whenever a new WiFi client station is discovered, launch a deauthentication attack and, whenever a new WiFi access point is discovered, try to associate to it:

> events.on wifi.deauth {{Client/mac}}
> events.on wifi.assoc {{mac}}

Start bettercap without colors and terminal effects and write events to the file ~/bettercap-events.log:

sudo bettercap -no-colors -eval "set ~/bettercap-events.log"