KismetDB
If the KismetDB log is enabled, Kismet exposes historic, searchable data.
If KismetDB logging is not enabled, these endpoints will not be available and will return an error.
Historic packets
When the kismetdb log type is enabled, fetch packets which match the filter statement from
the logfile.
Returns a PCAP-NG format stream of packets.
/logging/kismetdb/pcap/{TITLE}.pcapngGET
POSTPARAMETERS
TITLE
string
REQUIREDArbitrary file name
filter
multipleMultiple filter options
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.
filter
multiple
OPTIONALMultiple filter options
The filter options can be passed as individual arguments on the GET URI, as URI-encoded
variables (ie /logging/kismetdb/pcap/foo.pcapng?datasource=...&foo=...&bar=...), or passed
as a JSON command dictionary as a POST request.
Filters function as an AND statement: To match a packet, it must match all filter
terms.
Time window
Restrict packets by a timeframe which can be either bounded (both start and end times specified) or open-ended (only start or end specified)
timestamp_start
number
OPTIONALPosix timestamp with optional double precision as seconds.microseconds
timestamp_end
number
OPTIONALPosix timestamp with optional double precision as seconds.microseconds
Datasource
Limit packets to a specific datasource, by datasource UUID
datasource
string
OPTIONALDatasource UUID
Device key
Packets to, from, or otherwise associated with, the specified device.
device_id
string
OPTIONALKismet device key
Data link type
Match a specific data link type (DLT). This numeric DLT matches the libpcap link types and describes the physical frame type of the packet.
dlt
number
OPTIONALPCAP DLT value
Frequency
Match a specific, bounded, or open-ended frequency rage.
frequency
number
OPTIONALNatch a single frequency in KHz
frequency_min
number
OPTIONALMininum frequency, in KHz
frequency_max
number
OPTIONALMaximum frequency, in KHz
Signal
Match a bounded or open-ended window of signal levels.
Packets with no signal level are considered to have a signal level of 0.
signal_min
number
OPTIONALMinimum signal level
signal_max
number
OPTIONALMaximum signal level
Device MAC addresses
Match by MAC address, if available.
address_source
string
OPTIONALSource MAC address
address_dest
string
OPTIONALDestination MAC address
address_trans
string
OPTIONALTransmitter MAC aaddress (such as the AP BSSID on Wi-Fi)
Location
Filter by a bounded location of rectangular minimum and maximum coordinates.
Coordinates are decimal degrees in floating point format (123.456789).
location_lat_min
number
OPTIONALMinimum latitude
location_lon_min
number
OPTIONALMinimum longitude
location_lat_max
number
OPTIONALMaximum latitude
location_lon_min
number
OPTIONALMaximum longitude
Packet size
Match a bounded or unbounded packet size window.
size_min
number
OPTIONALMinimum packet size, in bytes
size_max
number
OPTIONALMaximum packet size, in bytes
Tags
tag
string
OPTIONALPacket tag to match
Limit
Limit the number of packets returned.
limit
number
OPTIONALReturn at most limit packets
Deleting packets
Delete all packets before drop_before from the KismetDB log.
On very long-running Kismet processes, this can be used to prevent the kismetdb from becoming unmanageable while retaining packet history, for instance by fetching all packets using the historic packet endpoint, then removing them from the kismetdb log.
/logging/kismetdb/pcap/drop.cmdPOSTPARAMETERS
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.
drop_before
OPTIONALPushing tagged data
Save an arbitrary JSON record in the kismetdb log, under a tag of your choosing. This can be used to keep data from other tools, such as sensor readings or camera images, in the same log and timeline as the Kismet data. Binary data, such as images, can be sent as base64 strings inside the JSON.
Records are saved to the snapshots table of the kismetdb log with the type API:<tag>, the
current time, and the current GPS location (if there is a GPS fix). The JSON is stored as
sent, in compact form.
Admin logins and API keys with the datalog role can push records; a datalog API key has no
access to any other endpoint, which makes it suitable for giving to an external tool.
Requests to this endpoint may be up to kis_log_tagged_data_max_size bytes, 8MB by default
(all other endpoints remain limited to 100KB). Larger requests are rejected with a 413
error. The larger limit only applies once the login has been accepted.
For example, saving an image from a camera:
$ curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
--data "{\"tag\": \"camera\", \"data\": {\"image\": \"$(base64 -w0 shot.jpg)\"}}" \
http://localhost:2501/logging/kismetdb/data/push.cmd
Records can be read back with the tagged data records endpoint, or
from a log file with sqlite3:
$ sqlite3 foo.kismet "SELECT ts_sec, lat, lon, json FROM snapshots WHERE snaptype = 'API:camera'"
This endpoint is only available when the kismetdb log is enabled.
admin
datalog/logging/kismetdb/data/push.cmdPOSTPARAMETERS
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.
tag
string
REQUIREDRecord tag; 1 to 64 letters, digits, ., _, or -
data
json
REQUIREDAny JSON value: an object, list, string, or number
JSON object:
| Field | Content |
|---|---|
ok | true |
tag | Tag of the saved record |
ts_sec | Timestamp of the record, in seconds |
ts_usec | Timestamp of the record, microseconds |
Listing tagged data
List the tags of the records saved with the tagged data push endpoint, in the current kismetdb log, sorted by tag.
This endpoint is only available when the kismetdb log is enabled.
readonly/logging/kismetdb/data/tags.jsonGET
POSTJSON list of tags:
| Field | Content |
|---|---|
tag | Tag |
count | Number of records with this tag |
first_ts_sec | Timestamp of the oldest record, in seconds |
last_ts_sec | Timestamp of the newest record, in seconds |
Reading tagged data
Read back the records saved with the tagged data push endpoint from the
current kismetdb log, oldest first. Without a tag, records of every tag are returned.
Options can be sent as URI parameters on a GET (ie
/logging/kismetdb/data/records.json?tag=camera&limit=10) or as a JSON command on a POST.
Records are returned in pages. When more is true, there are more records; request them
by passing the next value of the reply as after. A reply also stops early, with more set,
once it holds about 32MB of data; a reply always includes at least one record, so a single
large record can still be read. To find records without fetching their data, use data=false.
For example, fetching every camera record:
$ curl -H "Authorization: Bearer $KEY" \
"http://localhost:2501/logging/kismetdb/data/records.json?tag=camera&after=0"
Then repeat with after set to the next value until more is false.
Record ids are only meaningful within the same kismetdb log. A record whose stored data is
not valid JSON (for instance, if the log was edited by another tool) is returned with data set
to null.
Readonly logins and API keys can read records; datalog API keys can only push records, and
can not read them back.
This endpoint is only available when the kismetdb log is enabled.
readonly/logging/kismetdb/data/records.jsonGET
POSTPARAMETERS
tag
stringOnly records with this tag
after
numberOnly records after this record id
ts_start
numberOnly records at or after this time, in seconds
ts_end
numberOnly records at or before this time, in seconds
limit
numberReturn at most this many records, 1 to 1000; default 100
data
booleanfalse returns only the record details and size, without the data; default true
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.
tag
string
OPTIONALOnly records with this tag
after
number
OPTIONALOnly records after this record id
ts_start
number
OPTIONALOnly records at or after this time, in seconds
ts_end
number
OPTIONALOnly records at or before this time, in seconds
limit
number
OPTIONALReturn at most this many records, 1 to 1000; default 100
data
boolean
OPTIONALfalse returns only the record details and size, without the data; default true
JSON object:
| Field | Content |
|---|---|
ok | true |
records | List of records, below |
more | true if there are more records after these |
next | Id of the last record returned, to pass as after; missing when no records were returned |
Each record:
| Field | Content |
|---|---|
id | Record id |
tag | Tag |
ts_sec | Timestamp, in seconds |
ts_usec | Timestamp, microseconds |
lat | Latitude, or 0 if there was no GPS location |
lon | Longitude, or 0 if there was no GPS location |
size | Size of the stored data, in bytes |
data | The record data, as pushed; left out when data is false |
Deleting tagged data
Delete records saved with the tagged data push endpoint from the
current kismetdb log. Only tagged records are deleted; other data in the log, such as GPS
snapshots, POIs, devices, and packets, is never touched, even if its id is given in ids.
When more than one option is given, a record has to match all of them; for instance, tag
and ts_end together delete only the older records with that tag. A request with no options
is refused, so that an empty or mistaken request can not delete everything; to delete every
tagged record, send all set to true.
For example, deleting the camera records older than a day:
$ curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
--data "{\"tag\": \"camera\", \"ts_end\": $(( $(date +%s) - 86400 ))}" \
http://localhost:2501/logging/kismetdb/data/delete.cmd
Only admin logins can delete records; readonly and datalog API keys can not.
Deleting records frees space inside the kismetdb log for new data, but does not make the log
file smaller, and the deleted data may remain readable in the file until SQLite reuses that
space. To remove it from the file for good, clean the log with kismetdb_clean or
sqlite3 foo.kismet "VACUUM;" after Kismet has closed it.
This endpoint is only available when the kismetdb log is enabled.
admin/logging/kismetdb/data/delete.cmdPOSTPARAMETERS
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.
tag
string
OPTIONALOnly records with this tag
ids
list
OPTIONALOnly records with these record ids; a list of 1 to 1000 ids
ts_start
number
OPTIONALOnly records at or after this time, in seconds
ts_end
number
OPTIONALOnly records at or before this time, in seconds
all
boolean
OPTIONALtrue to delete every tagged record
JSON object:
| Field | Content |
|---|---|
ok | true |
deleted | Number of records deleted |