api.rest

A RESTful API server to orchestrate and interact with the current interactive session, starts on HTTP and unauthenticated by default, can be switched to HTTPS and basic auth by using the proper parameters.

Commands

api.rest on

Start the REST API server.

api.rest off

Stop the REST API server.

api.rest.record FILENAME

Start polling the rest API periodically recording each sample in a compressed file that can be later replayed.

api.rest.record off

Stop recording the session.

api.rest.replay FILENAME

Start the rest API module in replay mode using FILENAME as the recorded session file, will revert to normal mode once the replay is over.

api.rest.replay off

Stop replaying the recorded session.

Parameters

parameter default description
api.rest.certificate API TLS certificate (will be auto generated if not existing), fill to enable HTTPS.
api.rest.key API TLS key (will be auto generated if not existing), fill to enable HTTPS.
api.rest.certificate.bits 4096 Number of bits of the RSA private key of the generated HTTPS certificate.
api.rest.certificate.commonname bettercap Common Name field of the generated HTTPS certificate.
api.rest.certificate.country US Country field of the generated HTTPS certificate.
api.rest.certificate.locality Locality field of the generated HTTPS certificate.
api.rest.certificate.organization bettercap devteam Organization field of the generated HTTPS certificate.
api.rest.certificate.organizationalunit https://bettercap.org/ Organizational Unit field of the generated HTTPS certificate.
api.rest.address 127.0.0.1 Address to bind the API REST server to.
api.rest.port 8081 Port to bind the API REST server to.
api.rest.username API HTTP basic auth username.
api.rest.password API HTTP basic auth password.
api.rest.websocket false If true the /api/events route will be available as a websocket endpoint instead of HTTP.
api.rest.alloworigin * Value of the Access-Control-Allow-Origin header of the API server.
api.rest.record.clock 1 Number of seconds to wait while recording with api.rest.record between one sample and the next one.

Routes

Clients can authenticate using HTTP basic authentication, these are the available API routes.

GET /api/session

Get a JSON of the state of the current session, example response:

Expand for the example JSON

GET /api/session/lan

Get a JSON of the lan devices in the current session, example response:

Expand for the example JSON
Optional Arguments
  • Mac address, eg. GET /api/session/lan/00:AA:BB:CC:DD:11 - return information of a single lan endpoint with the mac address of 00:AA:BB:CC:DD:11 (the pihole from the above output).

GET /api/session/wifi

Get a JSON of the wifi devices (clients and access points) in the current session, example response:

Expand for the example JSON
Optional Arguments
  • Mac address, eg. GET /api/session/wifi/00:AA:BB:CC:DD:22 - return information of a single wifi endpoint with the mac address of 00:AA:BB:CC:DD:22 (the connected client from the above output).

GET /api/session/ble

Get a JSON of the BLE devices in the current session, example response:

Expand for the example JSON
Optional Arguments
  • Mac address, eg. GET /api/session/ble/00:AA:BB:CC:DD:33 - return information of a single ble endpoint with the mac address of 00:AA:BB:CC:DD:33 (the Adafruit Bluefruit LE client from the above output).

GET /api/session/hid

Get a JSON of the HID devices in the current session, example response:

Expand for the example JSON
Optional Arguments
  • Hardware address, eg. GET /api/session/hid/32:26:9f:a4:08 - return information of a single HID endpoint with the hardware address of 32:26:9f:a4:08.

GET /api/session/env

Get a JSON of the environment variables in the current session, example response:

Expand for the example JSON

GET /api/session/gateway

Get a JSON of the interface gateway of the current session, example response:

Expand for the example JSON

GET /api/session/interface

Get a JSON of the main interface (wifi/lan) of the current session, example response:

Expand for the example JSON

GET /api/session/options

Get a JSON of the options set for the current session, example response:

Expand for the example JSON

GET /api/session/packets

Get a JSON of the packet traffic for the current session, example response:

Expand for the example JSON

GET /api/session/started-at

Get a JSON of the time the current session was started, example response:

Expand for the example JSON

POST /api/session

Post a command to the interactive session, the JSON object being POSTed is expected to be:

Expand for the example JSON

While the response will be:

Expand for the example JSON

GET /api/events

This route will be available as a websocket endpoint instead of normal HTTP if the api.rest.websocket parameter is set to true.

Return a list of events ( the optional n GET parameter will limit the number ):

Expand for the example JSON

DELETE /api/events

Will clear the events buffer.