Devices

A device is the central record of a tracked entity in Kismet. Clients, bridges, access points, wireless sensors, and any other type of entity seen by Kismet will be a device. For complex relationships (such as 802.11 Wi-Fi), a list of related devices describes the access point-client relationship.

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.

The preferred method of retrieving device lists is to use the POST URI /devices/summary/ or /devices/last-time with a list of fields provided. Whenever possible, limiting the fields requested and the time range requested will reduce the load on the Kismet server and the client consuming the data.

Device summary and windowed device view

The device tracker uses device views to provide a windowed, sortable, searchable device list. This list is used by the main Kismet UI to display all devices, for instance.

This API supercedes the /devices/summary/ API.

  • URL

    /devices/views/all/…

    /devices/views/all/devices.json

    /devices/views/all/last-time/[TIMESTAMP]/devices.json

  • API added

    2019-06

  • Notes

    See the views api for detailed information on how to use the views endpoints.

Old Summarization & display

The device summarization endpoint is the primary interface for clients to access the device list. It is used heavily by the Kismet UI for the main device list table.

The device summarization is best utilized when applying a view window via the start and length variables.

  • URL

    /devices/summary/devices.json

  • DEPRECATED

    2019-06 While still available, this API has been deprecated in favor of the all device view.

  • Methods

    POST

  • Role

    readonly

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification
    regex Optional, regular expression filter
    colmap Optional column correlation info inserted by the Kismet Datatable UI for mapping jquery-datatables column information for proper ordering and sorting.
    datatable Optional, inserted by the Kismet Datatable UI to enable datatable mode which wraps the output in a container suitable for consumption by jquery-datatables.

    Additionally, when in datatables mode, the following HTTP POST variables are used:

    Key Description
    start Data view window start position
    length Datatable window end
    draw Datatable draw value
    search[value] Search term, applied to all fields in the summary vector
    order[0][column] Display column number for sorting, indexed with colmap data
    order[0][dir] Sort order direction from jquery-datatables

  • Results

    Summarized vector of devices.

Bulk device list

A special ekjson-only endpoint which provides a dump of all devices. This endpoint only returns ekjson-formatted data.

This endpoint is most useful for extracting bulk data and passing it to another tool like Elasticsearch.

  • URL

    /devices/all_devices.ekjson

  • Methods

    GET POST

  • Role

    readonly

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification

  • Results

    Each device is returned as a JSON object, one JSON record per line.

Activity & timestamp

Fetch devices which have been active since the supplied timestamp. This endpoint is typically used by scripted clients to monitor currently active devices.

  • URL

    /devices/last-time/[TIMESTAMP]/devices.json

    /devices/last-time/[TIMESTAMP]/devices.ekjson

    /devices/last-time/[TIMESTAMP]/devices.itjson

  • Methods

    GET POST

  • Role

    readonly

  • URL parameters

    Key Description
    [TIMESTAMP] Relative or absolute timestamp

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification
    regex Optional, regular expression filter

  • Results

    Vector of (optionally summarized and filtered) devices active since TS

Device by key

Fetch devices by the Kismet device key.

  • URL

    /devices/by-key/[DEVICEKEY]/device.json

  • Methods

    GET POST

  • Role

    readonly

  • URL parameters

    Key Description
    [DEVICEKEY] Kismet unique device key to match

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification

  • Results

    Device record, with optional simplification of the fields, matching DEVICEKEY

Device by MAC

Fetch devices which match the supplied MAC address. It is possible (though usually not likely) that there may be MAC address collisions between different PHY types. This becomes more likely when using non-Wi-Fi capture types which synthesize false MAC addresses because no official address is available, such as RTL-433, Mousejack, and other SDR-based datasources.

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

  • URL

    /devices/by-mac/[MACADDRESS]/devices.json

  • Methods

    GET POST

  • Role

    readonly

  • URL Parameters

    Key Description
    [MACADDRESS] Device MAC address to match

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification

  • Results

    Array of all devices with the supplied MAC address, optionally simplified by fields parameter.

Multiple devices by MAC

Fetch devices matching any of multiple MAC addresses (or partial MAC addresses). Typically used to monitor the presence of target devices.

This API will always return a vector of devices, even when only one device is matched.

The supplied MAC addresses can either be complete MACs (aa:bb:cc:dd:ee:ff), or partial-match masked MACs; for instance to match only the OUI 00:aa:bb, a masked MAC address of 00:aa:bb:00:00:00/ff:ff:ff:00:00:00 can be supplied, as defined in Keys and MAC addresses.

  • URL

    /devices/multimac/devices.json

    /devices/multimac/devices.ekjson

    /devices/multimac/devices.itjson

  • Methods

    POST

  • Role

    readonly

  • POST parameters

    A command dictionary containing:

    Key Desc
    devices Required, a vector of MAC addresses to be returned
    fields Optional, field simplification

  • Results

    Array of all devices matching any of the supplied MAC addresses.

Multiple devices by key

Fetch multiple devices matching any of the supplied keys. Typically used to retrieve the bulk status of many devices for display in the UI.

This API will always return a vector of devices, even when only one device is matched.

If a supplied key is not found, no device will be returned for that key.

  • URL

    /devices/multikey/devices.json

  • Methods

    POST

  • Role

    readonly

  • POST parameters

    A command dictionary containing:

    Key Desc
    devices Required, a vector of device keys to be returned
    fields Optional, field simplification

  • Results

    Array of all devices matching any of the supplied device keys.

Multiple devices by key (dictionary)

Fetch multiple devices matching any of the supplied keys. Typically used to retrieve the bulk status of many devices for display in the UI.

This API will always return a vector of devices, even when only one device is matched.

If a supplied key is not found, no device will be returned for that key.

  • URL

    /devices/multikey/as-object/devices.json

  • API added

    2020-08

  • Methods

    POST

  • Role

    readonly

  • POST parameters

    A command dictionary containing:

    Key Desc
    devices Required, a vector of device keys to be returned
    fields Optional, field simplification

  • Results

    Dictionary of all devices matching any of the supplied device keys, indexed by key.

Devices by capture source

The device tracker uses device views to provide a list of devices filtered by capturing data source:

  • URL

    /devices/views/seenby-uuid/[UUID]/…

    /devices/views/seenby-uuid/[UUID]/devices.json

    /devices/views/seenby-uuid/[UUID]/last-time/[TIMESTAMP]/devices.json

  • API added

    2019-03

  • URL Parameters

    Key Description
    [UUID] UUID of datasource

  • Notes

    See the views api for detailed information on how to use the views endpoints.

Phy handlers

A PHY handler in Kismet processes packets of a given physical layer; for instance Wi-Fi, Bluetooth, etc.

  • URL

    /phy/all_phys.json

  • Methods

    GET POST

  • Role

    readonly

  • API added

    2019-03

  • POST parameters

    A command dictionary containing:

    Key Description
    fields Optional, field simplification

  • Results

    Array of all phy types, including phy name, internal reference number, and packet and device counts.

Devices by PHY type

The device tracker uses device views to provide a list of devices filtered by the PHY data type:

  • URL

    /devices/views/phy/[PHYNAME]/…

    /devices/views/phy/[PHYNAME]/devices.json

    /devices/views/phy/[PHYNAME]/last-time/[TIMESTAMP]/devices.json

  • API added

    2019-03

  • URL Parameters

    Key Description
    [PHYNAME] UUID of datasource

  • Notes

    See the views api for detailed information on how to use the views endpoints.

Editing - device names

Devices can have an arbitrary user-supplied name.

  • URL

    /devices/by-key/[DEVICEKEY]/set_name.cmd

  • Methods

    POST

  • Role

    admin

  • URL Parameters

    Key Description
    [DEVICEKEY] Key of device to edit

  • POST parameters

    A command dictionary containing:

    Key Description
    username New name for device

  • Results

    HTTP 200 on success

    HTTP error on failure

Editing - device tags

Devices contain a collection of arbitrary tags which are held in the kismet.device.base.tags tree of the device record. These tags can be used to store persistent notes or other user-supplied or auto-generated data, and are keyed by the string tag name.

  • URL

    /devices/by-key/[DEVICEKEY]/set_tag.cmd

  • Methods

    POST

  • Role

    admin

  • URL Parameters

    Key Description
    [DEVICEKEY] Key of device to edit

  • POST parameters

    A command dictionary containing:

    Key Description
    tagname Tag being altered
    tagvalue Tag value being set

  • Results

    HTTP 200 on success

    HTTP error on failure

Alerts - device presence / absence - viewing

Kismet can raise an alert when a device (MAC address) is seen, or has been seen and is no longer present; this is controlled in kismet_alerts.conf by the devicefound and devicelost options.

These lists can be viewed real-time with the following:

  • URL

    /devices/alerts/mac/[type]/macs.json

    /devices/alerts/mac/[type]/macs.ekjson

    /devices/alerts/mac/[type]/macs.itjson

  • API added

    2020-11

  • Methods

    GET

  • Role

    readonly

  • URL Parameters

    Key Description
    [TYPE] Alert type to view, must be one of ‘found’, ‘lost’, or ‘both’

  • Results

    HTTP 200 on success and an array of MAC address being monitored under the given type

    HTTP error on failure

Alerts - device presence / absence - changing

Kismet can raise an alert when a device (MAC address) is seen, or has been seen and is no longer present; this is controlled in kismet_alerts.conf by the devicefound and devicelost options.

Devices can be added or removed from this list run-time:

  • URL

    /devices/alerts/mac/[type]/add.cmd

    /devices/alerts/mac/[type]/remove.cmd

  • API added

    2020-11

  • Methods

    POST

  • Role

    readonly

  • URL Parameters

    Key Description
    [TYPE] Alert type to set or clear, must be one of ‘found’, ‘lost’, or ‘both’

  • POST parameters

    A command dictionary containing:

    Key Description
    mac Single MAC address to modify
    macs Array of MAC addresses to modify

    A single MAC, or array of MACs, or both, may be specified. A MAC address must be provided in one of the options.

  • Results

    HTTP 200 on success

    HTTP error on failure

Realtime device monitoring

Devices can be monitored in realtime using the device monitor websocket connection.

By subscribing to devices, or groups of devices, a client can receive a websocket push event of device data. This data can be simplified by a standard field simplification system.

  • URL

    /devices/monitor.ws

  • API added

    2020-11

  • Methods

    WEBSOCKET (HTTP Upgrade + Websocket handshake)

  • Role

    readonly

  • URI parameters

    Key Description
    user Kismet administrative username, as HTTP URI-encoded variable
    password Kismet administrative password, as HTTP URI-encoded variable
    KISMET Kismet auth cookie, as HTTP URI-encoded variable

  • Result

    A websocket session with a subscription-model API

    HTTP error on failure

  • Notes

    Kismet websockets will accept authentication as HTTP basic auth headers, Kismet session token cookies, or HTTP URI-encoded GET parameters of the basic auth or session cookie.

  • Device monitoring API

    The device monitoring subscription API accepts JSON data to monitor (or stop monitoring) a device, a rate at which to report the device, a unique ID for this monitoring subscription, and an optional field simplification.

    Devices may be specified as a key, MAC address, or group of MAC addresses with a masking value, as defined in Keys and MAC addresses. If the special value of * is passed for the monitor key, all devices will be returned, making this endpoint suitable for use as a logging subscription service.

    The monitoring request ID should be a unique integer. It has no meaning except to the subscriber, and is used to cancel a monitoring request without closing the websocket.

    Device records will be sent to the subscriber if they have been modified within the specified rate. New subscribers will receive all matching device records.

  • Subscription API

    Multiple subscriptions can be made over time on a single websocket connection, so long as each request has a unique request ID. Duplicate IDs will unsubscribe the previous monitoring command.

    Key Description
    monitor Device identifier specified by key, MAC address, or group of MAC addresses with a masking value, as defined in Keys and MAC addresses. A value of * will return all devices.
    request Unique integer request ID, supplied by the client
    rate Rate, in seconds, to push updates
    fields Optional Kismet field simplification.
    format Optional export format. By default, json is used. For connecting to ELK-style services, ekjson will apply the ELK field name translations

  • Removal API

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

    Key Description
    cancel Unique identifier previously used to subscribe to requests

  • Example request

      % websocat ws://user:pass@localhost:2501/devices/monitor.ws
  {"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"]}

  {"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"}
  {"kismet.common.signal.last_signal": -76,"kismet.device.base.last_time": 1605736428,"kismet.device.base.key": "4202770D00000000_FFAABBDDCCEE"}

Updated: