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
`ble.connection.timeout`	Connection to the specified BLE device timed out.
`ble.device.characteristic.discovered`	A new characteristic has been discovered for a BLE device.
`ble.device.connected`	Connected to the selected BLE device.
`ble.device.lost`	A previously discovered BLE device is not in range anymore.
`ble.device.new`	A new BLE device has been discovered.
`ble.device.service.discovered`	A new service has been discovered for a BLE device.
`endpoint.new`	A new network host has been discovered.
`endpoint.lost`	A previously discovered network host disconnected from this network.
`gateway.change`	IPv4 or IPv6 gateway change detected.
`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.
`mod.started`	A specific module started.
`mod.stopped`	A specific module stopped.
`net.sniff.*`	A new payload has been sniffed.
`session.started`	The session started.
`session.closing`	The session is stopping.
`syn.scan`	An open port has been found on the target host.
`sys.log`	Simple log message event.
`tick`	An event generated by the ticker module.
`update.available`	An update is available.
`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.deauthentication`	WPA/WPA2 deauthentication frame has been detected.
`wifi.client.handshake`	WPA/WPA2 key material has been captured.
`wifi.client.lost`	A previously discovered WiFi client station disconnected from its AP.
`wifi.client.new`	A new WiFi client station has been discovered.
`wifi.client.probe`	A WiFi client station is sending a probe for an ESSID.

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`

Print the list of filters used to ignore events.

`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.http.format.hex`	`true`	If true dumped HTTP bodies will be in hexadecimal format.
`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.
`events.stream.output`		If not empty, events will be written to this file instead of the standard output.
`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.format`	`2006-01-02 15:04:05`	Datetime format to use for log rotation file names.
`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.time.format`	`15:04:05`	Date and time format to use for events reporting.

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"