events.stream

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.

Events

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.
endpoint.new A new network host has been discovered.
endpoint.lost A previously discovered network host disconnected from this network.
wifi.ap.new A new WiFi access point has been discovered.
wifi.ap.lost A previously discovered WiFi access point is not in range anymore.
wifi.client.new 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.
ble.device.new 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.
hid.device.new 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

events.stream on

Start the events stream.

events.stream off

Stop the events stream.

events.show 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.

events.filters.clear

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

events.clear

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).

events.triggers

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).

events.triggers.clear

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

Parameters

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

Examples

Start bettercap with full date and time format for events:

sudo bettercap -eval "set events.stream.time.format Mon Jan 2 15:04:05 -0700 MST 2006"

Show every event:

> events.show

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

> events.show 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 ble.device.new

Same thing but with a 10 seconds timeout:

> ble.recon on; events.waitfor ble.device.new 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.client.new wifi.deauth {{Client/mac}}
> events.on wifi.ap.new 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 events.stream.output ~/bettercap-events.log"