Devices

A device is the central record of a tracked entity in Kismet. Clients, bridges, access points, wireless sensors, and every other type of entity seen by Kismet will ultimately be a device.

Each PHY layer will add fields to the device record and populate thec ommon fields.

For complex relationships (such as 802.11 Wi-Fi), a list of related devices in the device record describes the access point-client relationship, shared hardware, etc.

All devices will have a basic set of records (held in the kismet.base.foo group of fields, generally) and sub-trees of records attached by the phy-specific handlers. A device may have multiple phy-specific records, for instance a device may contain both a device.dot11 record and a device.uav record if it is seen to be a Wi-Fi based UAV/Drone device.

Some care must be taken when requesting large numbers of device records: Kismet may be tracking tens or hundreds of thousands of devices in a single session, and requesting all devices can run both the Kismet server and your UI out of resources.

Whenever possible, use the pagination functions of the device view API and request devices groups.

Since the 2019-06 release, Kismet has migrated most device interactions to the device view api. Any new users of the API should use the device views.

Recently active devices

DESC

Returns devices which have been active (traffic observed from the device address) since the supplied timestamp.

Timestamps can be absolute or relative.

This endpoint is most typically used to repeatedly monitor recent devices, but can be replaced with the more efficient push-style device monitoring websocket below for many use cases.

ROLES
readonly
URI
/devices/last-time/{TIMESTAMP}/devices.json
/devices/last-time/{TIMESTAMP}/devices.ekjson
/devices/last-time/{TIMESTAMP}/devices.prettyjson
METHODS
GET POST
URI
PARAMETERS
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.

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.

Device by key

DESC

Fetch a complete device record (with optional simplification), indexed by the device key.

Typically a UI would use this endpoint to fetch a full device for displaying device details.

ROLES
readonly
URI
/devices/by-key/{DEVICEKEY}/device.json.json
/devices/by-key/{DEVICEKEY}/device.json.ekjson
/devices/by-key/{DEVICEKEY}/device.json.prettyjson
METHODS
GET POST
URI
PARAMETERS
DEVICEKEY string REQUIRED

Kismet unique device key for matching

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.

RETURN
JSON device object, or error.
RESPONSES
200
Success
404
No such device key
ERROR
Request error, such as malformed device key

Devices by MAC address

DESC

Fetch devices which match the supplied MAC address.

It is possibkle (though usually not likely) that there may be MAC address collisions between different PHY types. This becomes more likely when using either non-Wi-Fi datasources which synthesize completely artificial MAC addresses for indexing when no actual MAC address is available (such as RTL-433, ADSB, and other SDR based datasources), or when capturing two wireless devices from the same physical component, like a combo Wi-Fi/Bluetooth.

This API will always return a list of devices, even when only one device matches the supplied MAC address.

ROLES
readonly
URI
/devices/by-mac/{MACADDRESS}/devices.json.json
/devices/by-mac/{MACADDRESS}/devices.json.ekjson
/devices/by-mac/{MACADDRESS}/devices.json.prettyjson
METHODS
GET POST
URI
PARAMETERS
MACADDRESS string REQUIRED

MAC address for device matching

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.

RETURN
JSON list of device objects, or error.
RESPONSES
200
Success
404
No devices for supplied MAC address
ERROR
Request error, such as a malformed MAC address

Multiple devices by MAC addresses

DESC

Fetch devices matching any of multiple MAC address (or partial MAC address).

Typically this endpoint would be used to monitor the presence of target devices.

This API always returns a list of devices, even if only one device is matched.

ROLES
readonly
URI
/devices/multimac/devices.json
/devices/multimac/devices.ekjson
/devices/multimac/devices.prettyjson
METHODS
POST
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.

devices list of strings REQUIRED

A list of MAC addresses to search.

RETURN
JSON list of device objects, or error.
RESPONSES
200
Success
ERROR
Request error, such as a malformed MAC address

Multiple devices by key (as list)

DESC

Fetch devices matching any of multiple device keys.

Typically this endpoint would be used to monitor the presence of target devices.

This API always returns a list of devices, even if only one device is matched.

ROLES
readonly
URI
/devices/multikey/devices.json
/devices/multikey/devices.ekjson
/devices/multikey/devices.prettyjson
METHODS
POST
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.

devices list of strings REQUIRED

A list of device keys to search

RETURN
JSON list of device objects, or error.
RESPONSES
200
Success
ERROR
Request error, such as a malformed device key

Multiple devices by key (as dictionary)

DESC

Fetch devices matching any of multiple device keys.

Typically this endpoint would be used to monitor the presence of target devices.

This API returns a JSON dictionary of devices, indexed by device key.

ROLES
readonly
URI
/devices/multikey/as-object/devices.json
/devices/multikey/as-object/devices.ekjson
/devices/multikey/as-object/devices.prettyjson
METHODS
POST
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.

devices list of strings REQUIRED

A list of device keys to search

RETURN
JSON dictionary of device objects, or error.
RESPONSES
200
Success
ERROR
Request error, such as a malformed device key

Devices by capture source

DESC

A device view endpoint which automatically sorts devices by datasources.

For complete documentation, check the device view api

ROLES
readonly
URI
/devices/views/seenby-uuid/{UUID}/devices.json
/devices/views/seenby-uuid/{UUID}/devices.ekjson
/devices/views/seenby-uuid/{UUID}/devices.prettyjson
METHODS
GET POST
URI
PARAMETERS
UUID string REQUIRED

Data source UUID

NOTES
This endpoint uses the device view API.

Devices by capture source and timestamp

DESC

A device view endpoint which automatically sorts devices by datasources.

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

For complete documentation, check the device view api

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

Data source UUID

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.

NOTES
This endpoint uses the device view API.

Devices by capture phy

DESC

A device view endpoint which automatically sorts devices by phy layer type.

For complete documentation, check the device view api

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

PHY handler name. Information about PHY handlers can be found with the PHY handler endpoints

NOTES
This endpoint uses the device view API.

Devices by capture phy

DESC

A device view endpoint which automatically sorts devices by phy layer type.

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

For complete documentation, check the device view api

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

PHY handler name. Information about PHY handlers can be found with the PHY handler endpoints

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.

NOTES
This endpoint uses the device view API.

Editing device tags

DESC

Kismet devices contain a collection of arbitrary tag fields which are held in the kismet.device.base.tags tree.

These tags can be used to store persistent notes or other data, either user-supplied or auto-generated.

ROLES
admin
URI
/devices/by-key/{DEVICEKEY}/set_tag.cmd
METHODS
POST
URI
PARAMETERS
DEVICEKEY string REQUIRED

Key of target device

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.

tagname string REQUIRED

Device tag to set

tagvalue string REQUIRED

Tag value to set

RETURN
Empty document, state communicated via status code.
RESPONSES
200
Success
ERROR
Request error, such as a malformed device key

Device presence alerts (view)

DESC

Kismet can raise alerts when a device (by MAC address) is seen, or has been seen and is no longer present. These alerts are configured by the kismet_alerts.conf options devicefound and devicelost.

The list of devices being monitored can be viewed and altered realtime using these APIs.

ROLES
readonly
ADDED
API added 2020-11
URI
/devices/alerts/mac/{TYPE}/macs.json
/devices/alerts/mac/{TYPE}/macs.ekjson
/devices/alerts/mac/{TYPE}/macs.prettyjson
METHODS
GET
URI
PARAMETERS
TYPE string REQUIRED

Alert type to view, must be one of found lost or both

RETURN
Returns a JSON list of MAC addresses being monitored.
RESPONSES
200
Success
ERROR
Request error, such as an unknown alert type

Device presence alerts (changing)

DESC

Kismet can raise alerts when a device (by MAC address) is seen, or has been seen and is no longer present. These alerts are configured by the kisemt_alerts.conf options devicefound and devicelost.

The list of devices being monitored can be viewed and altered realtime using these APIs.

ROLES
admin
ADDED
API added 2020-11
URI
/devices/alerts/mac/{TYPE}/{ACTION}.cmd
METHODS
POST
URI
PARAMETERS
TYPE string REQUIRED

Alert type to view, must be one of found lost or both

ACTION string REQUIRED

Action to perform, must be one of add or remove

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.

mac string OPTIONAL

A single MAC to add or remove from the monitored list.

macs string OPTIONAL

A list of MACs to add or remove from the monitored list.

RETURN
Returns an empty document, with success of command communicated via HTTP status
RESPONSES
200
Success
ERROR
Request error, such as an unknown alert type

Realtime device monitoring

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
URI
/devices/monitor.ws
METHODS
WEBSOCKET UPGRADE
URI
PARAMETERS
user string OPTIONAL

Login user ID; most websocket client APIs do not support basic-auth, cookies, or other header-based login methods.

You must provide either user and password GET variables, or an API token or logins ession token via the KISMET GET variable.

password string OPTIONAL

Password associated with the user.

You must provide either user and password GET variables, or an API token or logins ession token via the KISMET GET variable.

KISMET string OPTIONAL

An API key or session token key.

You must provide either user and password GET variables, or an API token or logins ession token via the KISMET GET variable.

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

Legacy device summary

DEPRECATED
While still available for legacy code, this API has been deprecated in favor of the device view API all view.
DESC

The device summary API is the base API beneath a scrollable view of devices Kismet is tracking.

It is designed to be connected to a jquery-datatables view, but can be used by any UI mechanism with a concept of a scrolling sub-view.

Whenever possible, a UI is highly encouraged to use a scrolling window mechanism to view the devices: Kismet can track tens or hundreds of thousands of devices, and trying to render them all as a single view will likely over-tax both the Kismet server and whatever is rendering the UI.

When in datatables mode (datatable set to true in the JSON argument), this API takes additional FORM variables from the jquery-datatables implementation.

ROLES
readonly
URI
/devices/summary/devices.json
METHODS
GET POST
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 of system status snapshot.
RESPONSES
200
Basic success and JSON object
ERROR
On error (typically for malformed simplification)

Bulk device list

DEPRECATED

This endpoint can run smaller systems out of memory and is generally not encouraged.

A much safer method is to use the device view API all view, using sort-by first seen and a sliding window.

DESC

This is a special ekjson endpoint which provides a dump of all devices.

This endpoint only supports the ekjson method, and returns one object per row, formatted for use with a tool like Elastic Search.

ROLES
readonly
URI
/devices/all_devices.ekjson
/devices/all_devices.itjson
METHODS
GET POST
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.