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 theall
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 successHTTP 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 successHTTP 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 typeHTTP 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 successHTTP 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 themonitor
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"}