> Modules > Core > events.stream

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.
`tick`	An event generated by the ticker module.
`gateway.change`	IPv4 or IPv6 gateway change detected.
`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.
`wifi.client.deauthentication`	WPA/WPA2 deauthentication frame has been detected.
`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"