Device views

Device views in Kismet are optimized subsets of the global device list.

Device views can by defined by PHY handlers, plugins, as part of the Kismet basic code, or by user-supplied data.

Kismet uses device views to organize devices by capture interface, phy type, specific device type (like the phy80211 access point view), and more.

All clients are strongly encouraged to use the device view API going forwards.

Device views are also designed to work with paginating user interfaces; as part of the request, a client can request a “page” of information; with each subsequent page (or scroll) the user interface fetches only the data it needs.

The Kismet device views are written around the API of the jquery-datatables web component API, but this API can easily be adapted for use with any pagination system.

List device views

DESC
Return a list of all defined device views, and a summary of the numbers of devices in each view.
ROLES
readonly
URI
/devices/views/all_views.json
/devices/views/all_views.ekjson
/devices/views/all_views.prettyjson
METHODS
GET
RETURN
JSON list of view data

View-based device lists

DESC

The View device API is the primary interface for clients to access the device list and for scripts to retrieve lists of devices.

It is designed to be directly interfaced with a paginating display mechanism, and is best utilized when applying a view window via the start and length variables.

ROLES
readonly
URI
/devices/views/{VIEWID}/devices.json
/devices/views/{VIEWID}/devices.ekjson
/devices/views/{VIEWID}/devices.prettyjson
METHODS
POST
URI
PARAMETERS
VIEWID string REQUIRED

Named device view

POST
PARAMETERS
start number OPTIONAL

When in datatables mode, the start of the windowed view.

length number OPTIONAL

When in datatables mode, the length of the windowed view.

draw number OPTIONAL

When in datatables mode, the datatable draw sequence number.

search[value] string OPTIONAL

When in datatables mode, the search term to be applied to all fields in the summary list.

order[0][column] string OPTIONAL

When in datatables mode, the display column number for shorting, indexed by the colmap JSON data parameter.

order[0][dir] string OPTIONAL

When in datatables mode, the sort direction sent by jquery-datatables.

JSON
PARAMETERS

This endpoint takes additional parameters by using a `POST` request and supplying a JSON document or json form variable.

You can find more information about API parameters here.

fields field simplification OPTIONAL

Kismet can reduce the amount of information being processed and returned by an API by simplifying the fields to only return the data needed by the caller.

You can read more about the field simplification API and how to use it here.

regex regular expression OPTIONAL

When compiled with PCRE support, Kismet can apply regular expression filters.

Regular expressions can be applied to multiple fields.

You can read more about the field regex API and how to use it here.

colmap list OPTIONAL

Column map information generated by the Kismet UI for mapping jquery-datatable column information for sorting and ordering.

datatable boolean OPTIONAL

Wrap output in a container suitable for connecting to a jquery-datatable container in the web UI.

RETURN
JSON object containing the list of devices and metadata for jquery-datatables.
RESPONSES
200
Basic success and JSON object
ERROR
On error (typically for malformed simplification)
NOTES
In datatables mode, this endpoint takes both a json=... command dictionary and typical FORM post variables. This is necessary to work within the datatables request structure.

Devices by view and time

DESC

Devices which have been active since the specified time will be returned.

For real-time monitoring, the device monitoring websocket is often more efficient.

ROLES
readonly
URI
/devices/views/{VIEWID}/last-time/{TIMESTAMP}/devices.json
/devices/views/{VIEWID}/last-time/{TIMESTAMP}/devices.ekjson
/devices/views/{VIEWID}/last-time/{TIMESTAMP}/devices.prettyjson
METHODS
GET POST
URI
PARAMETERS
VIEWID string REQUIRED

Named device view

TIMESTAMP number REQUIRED

Timestamps can be absolute (UNIX epochal) timestamps, or they can be relative negativ numbers, indiciating "number of seconds before now".

You can read more about timestamp handling and how to use it here.

POST
PARAMETERS
start number OPTIONAL

When in datatables mode, the start of the windowed view.

length number OPTIONAL

When in datatables mode, the length of the windowed view.

draw number OPTIONAL

When in datatables mode, the datatable draw sequence number.

search[value] string OPTIONAL

When in datatables mode, the search term to be applied to all fields in the summary list.

order[0][column] string OPTIONAL

When in datatables mode, the display column number for shorting, indexed by the colmap JSON data parameter.

order[0][dir] string OPTIONAL

When in datatables mode, the sort direction sent by jquery-datatables.

JSON
PARAMETERS

This endpoint takes additional parameters by using a `POST` request and supplying a JSON document or json form variable.

You can find more information about API parameters here.

fields field simplification OPTIONAL

Kismet can reduce the amount of information being processed and returned by an API by simplifying the fields to only return the data needed by the caller.

You can read more about the field simplification API and how to use it here.

regex regular expression OPTIONAL

When compiled with PCRE support, Kismet can apply regular expression filters.

Regular expressions can be applied to multiple fields.

You can read more about the field regex API and how to use it here.

colmap list OPTIONAL

Column map information generated by the Kismet UI for mapping jquery-datatable column information for sorting and ordering.

datatable boolean OPTIONAL

Wrap output in a container suitable for connecting to a jquery-datatable container in the web UI.

RETURN
JSON list of devices in VIEWID with activity more recent than TIMESTAMP.

Realtime device monitoring by view

DESC

Devices can be monitored in realtime using the device monitor websocket API, which will push device changes to listeners as they occur.

By subscribing to devices, or groups of devices, a client can receive a push event of the device record.

The device data pushed can also be simplified by the standard field simplification.

ROLES
readonly
ADDED
API added 2021-01
URI
/devices/views/{VIEWID}/monitor.ws
METHODS
WEBSOCKET UPGRADE
URI
PARAMETERS
VIEWID string REQUIRED

Named device view

user string

User to log in as; websockets do not support standard basic-auth, cookies, or other header-based login methods.

You must provide either user and password parameters, or an API token or login session token via the KISMET paraeter.

password string

Password associated with the login user.

You must provide either user and password parameters, or an API token or login session token via the KISMET parameter.

KISMET string

Kismet auth token or API key.

You must provide either user and password parameters, or an API token or login session token via the KISMET parameter.

API

The device monitoring subscription API accepts JSON objects with a subscription or removal request for a device or group of devices specified by key, MAC, or group MAC, and optional field simplification.

Subscription API

Multiple subscriptions can be made on a single websocket connection, so long as each subscription request has a unique ID. Use of duplicate IDs will automatically unsubscribe the previous subscription.

monitor string REQUIRED

Device identifier specified by key, MAC, or group of MACs with a masking value, as defined in Keys and MACs.

The wildcard * can be used to monitor all devices.

request number REQUIRED

Unique request ID, supplied by the client. This ID will be used if the client wishes to unsubscribe from events in the future via the cancel API.

rate number REQUIRED

Rate limit, in seconds, to push updates. More frequent device updates are discarded.

fields field simplification OPTIONAL

Kismet can reduce the amount of information being processed and returned by an API by simplifying the fields to only return the data needed by the caller.

You can read more about the field simplification API and how to use it here.

Removal API

To cease monitoring a device (or group of devices) without disconnecting the websocket, use the unsubscribe API.

cancel number REQUIRED

Stop monitoring reports from the provided id.

EXAMPLE

Constructing and connecting a websocket uses the standard Javascript websocket API, we’ll request all devices with the OUI of AA:BB:CC, updated at once per second, fetching the key, last-active time, and last signal level.

var ws = new WebSocket('ws://host:2501/devices/views/FOOBAR/monitor.ws?'
  'user=username&password=password');
ws.onmessage = function(msg) {
    var json = JSON.parse(msg.data);
    console.log(json);
}
ws.onopen = function(event) {
    var req = {
        "monitor": "AA:BB:CC:00:00:00/FF:FF:FF:00:00:00",
        "request": 31337,
        "rate": 1,
        "fields": [ 
          "kismet.device.base.key",
          "kismet.device.base.last_time",
          "kismet.device.base.signal/kismet.common.signal.last_signal"
        ],
    }
    ws.send(JSON.stringify(req));
}

This would return pushed records like:

{
  "kismet.common.signal.last_signal": -77,
  "kismet.device.base.last_time": 1605736428,
  "kismet.device.base.key": "4202770D00000000_AABBCCDDEEFF"
}

{
  "kismet.common.signal.last_signal": -81,
  "kismet.device.base.last_time": 1605736427,
  "kismet.device.base.key": "4202770D00000000_001122334455"
}

Which would be highly appropriate for monitoring signal levels of a group of devices, for instance.