├── README.md ├── devel ├── .gitignore ├── adding_tag_parsers.md ├── datasource.md ├── datasource_capframework.md ├── datatracker.md ├── helper_interface.md ├── log_kismet.md ├── pcapng_gps.md ├── plugin.md ├── plugin_http_helper.md ├── rest │ ├── 000-rest_endpoints.md │ ├── 001-api_updates.md │ ├── 005-exploring.md │ ├── 010-serialization.md │ ├── 015-logins_and_sessions.md │ ├── 020-commands.md │ ├── 021-keys_and_macs.md │ ├── 030-system.md │ ├── 031-eventbus.md │ ├── 035-devices.md │ ├── 040-device_views.md │ ├── 045-messages.md │ ├── 050-alerts.md │ ├── 055-channels.md │ ├── 060-datasources.md │ ├── 065-gps.md │ ├── 070-packet_capture.md │ ├── 071-packet_filter.md │ ├── 075-plugins.md │ ├── 080-streams.md │ ├── 085-logging.md │ ├── 086-poi.md │ ├── 090-kismetdb.md │ ├── 095-phydot11.md │ ├── 101-phydot11_ssidscan.md │ ├── 102-phydot11_scansource.md │ ├── 103-phydot11_ssidtracker.md │ ├── 105-phyuav.md │ ├── 110-phybluetooth_bluetoothscan.md │ ├── 115-phyadsb.md │ ├── _base.md │ └── _links.md ├── tracked_component.md ├── webui.jquery.kismet.devicedata.md └── webui.md ├── howto ├── openwrt.md ├── remote-capture-build.md └── win10.md ├── jupyter └── intro_to_pandas.ipynb └── readme ├── 000-intro.md ├── 001-git_version.md ├── 005-quickstart_compiling.md ├── 006-packages.md ├── 010-suid.md ├── 011-starting.md ├── 015-upgrading.md ├── 020-debugging.md ├── 025-config_files.md ├── 026-packaging.md ├── 030-config_logging.md ├── 031-logging_kismetdb.md ├── 031-logging_pcap.md ├── 031-logging_wiglecsv.md ├── 035-generic_datasources.md ├── 040-datasources_wifi.md ├── 045-datasources_bluetooth.md ├── 046-datasources_802154.md ├── 050-datasources_pcapfile.md ├── 051-datasources_kismetdb.md ├── 055-datasources_sdr_rtl433.md ├── 056-datasources_sdr_rtlamr.md ├── 057-datasources_sdr_rtladsb.md ├── 060-datasources_mousejack.md ├── 070-alerts.md ├── 080-remote_capture.md ├── 085-server_announcing.md ├── 100-webserver.md ├── 110-gps.md ├── 120-performance_and_mem.md ├── 150-siem.md ├── 160-logs_wigle.md ├── 161-logs_json.md ├── 162-logs_strip_packets.md ├── 163-logs_to_pcap.md ├── 164-logs_statistics.md ├── 165-logs_kml.md ├── 180-wardrive_mode.md ├── 200-libraries.md └── _base.md /README.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED 2 | 3 | This repo is now merged into the kismet-web-docs repo, and all future changes should go there. 4 | 5 | The new site engine uses Hugo, and a number of the documentation parts have been converted to 6 | YAML data with templates. 7 | -------------------------------------------------------------------------------- /devel/.gitignore: -------------------------------------------------------------------------------- 1 | .*.swp* 2 | -------------------------------------------------------------------------------- /devel/datasource_capframework.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Datasource capframework library" 3 | permalink: /docs/devel/datasources_capframework/ 4 | toc: true 5 | docgroup: "devel-cpp" 6 | excerpt: "The datasource captureframework C API" 7 | --- 8 | ## Extending Kismet: Datasource Capture Framework Pure-C API 9 | 10 | Kismet supports capturing from any binary capable of talking a simple IPC/network protocol. 11 | 12 | To minimize the requirements and simplify embedding capture code in small embedded systems without a C++ runtime, `capture_framework.h` and `capture_framework.c` implement the protocol and main communications loops in a pure-c helper library. 13 | 14 | ## Pure-C 15 | 16 | Capture-Framework is written in pure-c which should be compatible with C99 and does not require any C++ runtimes. The Kismet plugins and decoders still require C++. 17 | 18 | ## Communication 19 | 20 | Kismet capture binaries communicate over IPC on a shared pipe, or via a TCP network connection to the Kismet server. When using piped IPC, the pipe pairs are passed to the exec()'d capture binary in the --in-fd and --out-fd command line options. 21 | 22 | Data is buffered in generic, simplistic ring buffer structures and dispatched via a standard select() loop. 23 | 24 | ## Threads 25 | 26 | Capture-Framework uses pthreads to spawn two threads, in addition to the primary main thread: 27 | 28 | ### Capture Thread 29 | 30 | The capture callback (more on these soon) is run in an independent, cancelable thread. This allows the capture calls on a binary to block without interfering with the standard select() loop and communication with the Kismet server. 31 | 32 | ### Channel Hopping Thread 33 | 34 | If channel hopping is enabled in the capture binary, an independent thread performs the timing and channel set commands. 35 | 36 | ## Callbacks 37 | 38 | All expandable functions in Capture-Framework are handled by passing callback functions; listing devices, probing, opening, setting channels, etc, are handled by callback functions and can be trivially customized. 39 | 40 | # Order of Operations 41 | 42 | Kismet will launch a capture binary and perform one of several actions: 43 | 44 | ## List devices 45 | 46 | This is called on all capture drivers to create a list of devices the user could pick. The capture binary is responsible for enumerating any devices it can support via any mechanism; for instance the Linux Wi-Fi capture binary enumerates devices by processing the /sys/class/net/ pseudofilesystem. 47 | 48 | After listing devices, a capture binary should go into a spindown/pending state and wait to be closed; no other action will be taken this execution. 49 | 50 | ## Probe definition 51 | 52 | This is called to determine the driver which can handle a definition, when no type is explicitly specified. The capture binary is responsible for determining if this looks like a source that can be opened. For example, the pcapfile capture will attempt to open the definition as a pcap; the Linux Wi-Fi capture will attempt to retrieve the interface channel via SIOCGIWCHAN to determine if it looks to be a Wi-Fi device. 53 | 54 | After returning a probe response, a capture binary should go into a spindown/pending state and wait to be closed; no other action will be taken this execution. 55 | 56 | ## Open definition 57 | 58 | This is called to actually open and begin capturing from an interface. 59 | 60 | -------------------------------------------------------------------------------- /devel/plugin.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Creating Kismet plugins" 3 | permalink: /docs/devel/plugins/ 4 | toc: true 5 | docgroup: "devel" 6 | excerpt: "Kismet plugins can change server behavior (via C++ plugins), interface behavior (via Javascript), or both" 7 | --- 8 | Kismet can load additional code dynamically at runtime in the form of a plugin. 9 | 10 | Plugins are a double-edged sword: In their current implementation, plugins are full first-class citizens in the Kismet ecosystem; a plugin can perform any action Kismet native code can perform, and are given a direct reference to the internal Kismet module system. 11 | 12 | ## Plugin code 13 | 14 | Plugins are shared objects (.so files) with pre-defined functions, HTML and Javascript code, or external binaries launched over IPC which communicate with the Kismet server. Plugins can combine all of these aspects. 15 | 16 | 17 | ## Plugin locations 18 | Plugins can be installed into one of two locations: 19 | 20 | * System-wide plugins are installed into `[datadir]/kismet/plugins/` where `[datadir]` is the parameter passed to `./configure --datadir=...`. It defaults to `/usr/local/`. 21 | 22 | * Per-user plugins are installed into the users home directory under `~/.kismet/plugins/` 23 | 24 | 25 | ## Plugin static web content 26 | Plugins are mapped into the Kismet webserver under `/plugin/[plugin-directory-name]/` path. Plugins can add arbitrary content in this directory, but it is strongly recommended that they follow the following convention: 27 | 28 | * `[prefix]/plugins/[name]/httpd/js/` - Javascript files 29 | * `[prefix]/plugins/[name]/httpd/css/` - CSS files 30 | 31 | To register a JS module for automatic loading (for instance, to interact with the normal Kismet web UI and add new tabs, details, etc), a plugin must either: 32 | 33 | * Register the module with with the `kis_httpd_registry::register_js(...)` system 34 | * Define a plugin manifest stored in `[prefix]/plugins/[name]/manifest.conf` 35 | 36 | ## Plugin external HTTP helpers 37 | An external HTTP helper plugin communicates with Kismet over the external API IPC channel. The binary is launched by Kismet. External API plugins can add new endpoints to the Kismet server and communicate with Kismet via the IPC channel and the Kismet web API. 38 | 39 | ## Plugin manifests 40 | The manifest file allows Kismet to automatically derive information about a plugin with no native code - this allows for simple HTTP-only plugins which enhance the web UI without requiring them to include compiled code to register the plugin. 41 | 42 | The manifest file should be placed in `[prefix]/plugins/[name]/manifest.conf`, and takes the form of a Kismet config file (name=value pairs): 43 | 44 | | Key | Content | 45 | | ---- | ------- | 46 | | name | Plugin name | 47 | | description | Plugin description | 48 | | author | Plugin author | 49 | | version | Plugin version | 50 | | object | plugin shared object file name | 51 | | httpexternal | external API tool binary name | 52 | | js | JS module and path as `module_name,/web/path/to/js`. | 53 | 54 | Example manifest: 55 | ``` 56 | name=Webplugin 57 | description=Trivial web-only plugin 58 | author=Joe Random 59 | version=1.0.0 60 | 61 | js=new_web_module,/plugin/webplugin/js/new_web_module.js 62 | ``` 63 | 64 | Example manifest for plugin with C++ code: 65 | ``` 66 | name=Codeplugin 67 | description=Standard code-based plugin 68 | author=Joe Random 69 | version=1.0.0 70 | 71 | object=kismet-codeplugin.so 72 | 73 | js=code_web_module,/plugin/codeplugin/js/code_web_module.js 74 | ``` 75 | 76 | Example manifest for plugin with an external binary: 77 | ``` 78 | name=ProxyDemo 79 | description=Demo of a plugin using the external API tool to create new endpoints 80 | author=Joe Random 81 | version=1.0.0 82 | 83 | httpexternal=kismet_proxydemo 84 | js=proxied_web_module,/plugin/proxydemo/js/proxied_web_module.js 85 | ``` 86 | 87 | -------------------------------------------------------------------------------- /devel/rest/000-rest_endpoints.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "REST webserver endpoints" 3 | permalink: /docs/devel/webui_rest/endpoints/ 4 | docgroup: "devel-rest" 5 | excerpt: "The Kismet REST-like API" 6 | --- 7 | 8 | Kismet uses a REST-like interface for the embedded webserver, which provides data and accepts commands. 9 | 10 | When fetching data, whenever possible, parameters are passed as part of the GET URI, but for more complex features, command arguments may be sent via POST variables. 11 | 12 | Kismet supports multiple output formats; whenever possible, an endpoint will support all output formats. The default output format used in examples is JSON, but additional output types may be added in the future or added by run-time plugins. Some unique endpoints are available only under specific output methods because they take advantage of features of that output type. 13 | 14 | As of `2019-04-git`, Kismet requires a login on ALL rest endpoints, excluding `/system/user_status`, `/session/check_login`, `/session/check_session`, and `/session/check_setup_ok` 15 | -------------------------------------------------------------------------------- /devel/rest/001-api_updates.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "API Changes and Updates" 3 | permalink: /docs/devel/webui_rest/changes/ 4 | docgroup: "devel-rest" 5 | excerpt: "Significant changes to the API endpoints" 6 | --- 7 | 8 | Over time, the Kismet endpoint API will change - while efforts are made to retain compatibility whenever possible, some changes will require breaking older implementations. These significant changes will be documented here. 9 | 10 | * `2022-01-R3` 11 | 12 | Changes to the REST API: 13 | 14 | * Added `WEBGPS` role to the [webgps POST API](/docs/devel/webui_rest/gps/#web-gps) 15 | * Soft-launched the [metagps API](/docs/devel/webui_rest/gps/#meta-gps) for remote capture GPS 16 | 17 | * `2022-01-R2` 18 | 19 | Changes to the REST API: 20 | 21 | * Added regex to [device view by time](/docs/devel/webui_rest/device_views/#devices-by-view--time) 22 | 23 | * `2022-01-R1` 24 | 25 | Changes to the REST API: 26 | * Added the option to [filter pcap-ng streams](/docs/devel/webui_rest/kismetdb/#filter-options) by packet tag 27 | * Added [additional events](/docs/devel/webui_rest/eventbus/#dot11_advertised_ssid) to the eventbus, including the first packet for advertised SSIDs, responding SSIDs, and probed SSIDs. 28 | 29 | Changes to the kismetdb database: 30 | * Updated to version 8 of kismetdb, which [adds additional packet metadata](/docs/devel/kismetdb/#version-8) 31 | 32 | Changes to pcapng logging: 33 | * Added pcapng style CRC32 hashes and packet identifier numbers for multi-interface captures 34 | 35 | Changes to ipc/remote: 36 | * Added v2 ipc protocol to optimize for fast construction / zero memcpy 37 | 38 | * `2021-05-R1` 39 | 40 | Changes to the REST API: 41 | * Added a [view-specific device subscription API](/docs/devel/webui_rest/device_views/#realtime-device-monitoring-by-view) under `/device/views/[VIEWID]/monitor.ws` 42 | * Added a [datasource-specific ADSB hex API](/docs/devel/webui_rest/phyadsb/#adsb-raw-hex-wbesocket-per-source) under `/datasource/by-uuid/[uuid]/adsb_raw.ws` 43 | * Added `class` and `severity` to [alert definitions](/docs/devel/webui_rest/alerts/#defining-alerts) and returned alerts 44 | 45 | * `2020-12-R1` - Major rewrites of HTTP and networking, memory optimizations 46 | 47 | This version introduces a complete rewrite of the internal webserver implementation, changing the core webserver library to Boost::Beast and rewriting how endpoints are processed and parsed. 48 | 49 | Changes to the REST API: 50 | * 802.11 handshake pcaps are now found on `/phy/phy80211/by-key/[key]/pcap/handshake.pcap` and `/phy/phy80211/by-key/[key]/pcap/handshake-pmkid.pcap`. The original MAC-based filenames are passed with the `attachment; filename=...` header. 51 | * Per-uuid pcapng streams are now found at `/datasource/pcap/by-uuid/[uuid]/packets.pcapng` 52 | * Per-device pcapng streams are now found at `/devices/pcap/by-key/[key]/packets.pcapng` 53 | * Phy80211 per-bssid pcap streams are now found at `/phy/phy80211/pcap/by-bssid/[mac]/packets.pcapng` 54 | * All REST endpoints in the API now use `cmd` as the file extension for all commands, deprecating and removing the `jcmd` extension fully (which has not been a documented command extension for several releases already). 55 | * Websockets are now implemented in the Kismet webserver, with the Eventbus websocket being the largest user. 56 | * `wget` is now supported by detection of the user-agent field; a full HTTP 401 and WWW-Authenticate header is sent to accommodate `wget` not sending basic-auth until it fails an auth check. 57 | * HTTP GET variables are now properly supported 58 | * [API keys and roles](/docs/devel/webui_rest/logins/#api-tokens-and-roles) are now supported 59 | * JSON data accepted as application/json as well as application/x-form-urlencoded 60 | * Authentication may be passed as `user`, `password`, or `KISMET` GET URL variables 61 | 62 | New endpoints: 63 | * Realtime message, alert, GPS, system status, and more via the [eventbus](/docs/devel/webui_rest/eventbus/) websocket at `/eventbus/events.ws` 64 | * [API auth token manipulation](/docs/devel/webui_rest/logins/#api-tokens-and-roles) endpoints on `/auth/apikey/generate.cmd`, `/auth/apikey/revoke.cmd`, and `/auth/apikey/list.json`. 65 | * Runtime [changing of the devicefound/deviceleft alert list](/docs/devel/webui_rest/devices/#alerts---device-presence--absence---changing) via `/devices/alerts/mac/[type]/add.cmd`, `/devices/alerts/mac/[type]/remove.cmd` and `/devices/alerts/mac/[type]/macs.json` 66 | * Live [ADSB data](/docs/devel/webui_rest/phyadsb/) in text/hex mode via `ws://.../phy/RTLADSB/raw.ws`, streams a text-based hex output of the ADSB data 67 | * Live [ADSB data](/docs/devel/webui_rest/phyadsb/) in binary/beast mode via `ws://.../phy/RTLADSB/beast.ws`, streams a binary beast-protocol ADSB dump 68 | * Subscription-style [live device monitoring](/docs/devel/webui_rest/devices/#realtime-device-monitoring) websocket endpoint at `ws://.../devices/monitor.ws` 69 | 70 | 71 | Changes to data: 72 | * Locational data no longer includes the `avg_lat`, `avg_lon`, or `avg_alt` and related fields that held the *raw* averages of location. The average location *is still present* in average location object, this removal affects only the internal raw values which were exposed to serialization. 73 | * Locational data no longer includes the `kismet.common.location.valid` field, as it was redundant - this data is contained in `kismet.common.location.fix` when the fix is >= 2. 74 | * Location data no longer includes the 'history cloud', an attempt to provide a RRD-like history log; it used way too much RAM and was not used anywhere. 75 | * Some locations (such as min/max/average) no longer track speed and heading, saving more ram 76 | * Server UUID in device records is now a common shared field under the name `kismet.server.uuid` 77 | * Non-json command endpoints (mostly) now return text/plain 78 | * RRDs no longer include the aggregator string name 79 | 80 | * `2020-08` several maps made optional/dynamic 81 | 82 | To save RAM, several maps and vectors are now flagged as optional; if there is no content in those fields, they will not be present in the generated JSON. Consumers should always check for presence of the map in the returned data before trying to use it. 83 | 84 | Fields made dynamic: 85 | * `kismet.device.base.tags` 86 | * `dot11.device/dot11.device.client_map` 87 | * `dot11.device/dot11.device.advertised_ssid_map` 88 | * `dot11.device/dot11.device.probed_ssid_map` 89 | * `dot11.device/dot11.device.associated_client_map` 90 | * `dot11.device/dot11.device.wpa_nonce_list` 91 | * `dot11.device/dot11.device.wpa_anonce_list` 92 | 93 | To save RAM, the `kismet.device.base.tags` sub-map is now optional; if there are no tags in a device, this field will not exist in the serialized JSON data. Consumers of this data should check that `kismet.device.base.tags` is present in the device map. 94 | 95 | * `2019-10` geopoint 96 | 97 | To more cleanly support ELK, all location records now use `geopoint` formats. A geopoint is an array containing `[lon, lat]`. `kismet.common.location.lat` and `kismet.common.location.lon` are now `kismet.common.location.geopoint`. 98 | 99 | * `2019-10` advertised_ssid and probe_ssid as arrays 100 | 101 | To more cleanly support ELK the advertised ssid and probed ssid components of dot11 devices are now serialized as vectors instead of maps. Previously these were serialized as maps with a key of the hash of the SSID and attributes (an essentialy meaningless number in the export). Now these are sent as an array of advertised or probed SSID objects. 102 | 103 | 104 | * `2019-10` ekjson and itjson 105 | 106 | To more cleanly support ELK EKJSON format, the `ekjson` serialization now permutes the field names to transform all `.` to `_`. This brings it in line with the ELK interpretation that a `.` is a field separator. To access the old implemention, where the field names are unmodified, use the new `itjson` (or 'iterative json') format; it will return results which are a vector of objects as an object per line, suitable for serialized parsing and processing. 107 | 108 | * `2019-04` Mandatory authentication 109 | 110 | Kismet now requires authentication on *ALL* endpoints, with the exclusion of `/system/user_status`, `/session/check_login`, `/session/check_session`, and `/session/check_setup_ok`. 111 | 112 | -------------------------------------------------------------------------------- /devel/rest/005-exploring.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Exploring endpoints" 3 | permalink: /docs/devel/webui_rest/exploring/ 4 | docgroup: "devel-rest" 5 | excerpt: "Exploring the REST API should be simple, here's how to get the most out of the endpoints and self-documenting fields." 6 | --- 7 | 8 | ## Exploring the REST system 9 | 10 | The easiest way to explore the REST system, aside from the docs, is to query the JSON endpoints directly. Remember that as of `2019-04-git` you will need to have a valid login to explore the server setup. You can use `curl` and `python` to quickly grab output and format the JSON to be human readable: 11 | 12 | ``` 13 | $ curl http://user:password@localhost:2501/datasource/all_sources.json | python -mjson.tool 14 | % Total % Received % Xferd Average Speed Time Time Time Current 15 | Dload Upload Total Spent Left Speed 16 | 100 36274 100 36274 0 0 761k 0 --:--:-- --:--:-- --:--:-- 770k 17 | [ 18 | { 19 | "kismet.datasource.capture_interface": "wlp3s0mon", 20 | "kismet.datasource.channel": "", 21 | "kismet.datasource.channels": [ 22 | "1", 23 | "1HT40+", 24 | "2", 25 | "3", 26 | "4", 27 | "5", 28 | "6", 29 | "6HT40-", 30 | "6HT40+", 31 | "7", 32 | "8", 33 | "9", 34 | "10", 35 | "11", 36 | "11HT40-" 37 | ], 38 | "kismet.datasource.definition": "wlp3s0", 39 | "kismet.datasource.dlt": 127, 40 | "kismet.datasource.error": 0, 41 | "kismet.datasource.error_reason": "", 42 | "kismet.datasource.hop_channels": [ 43 | .... 44 | ``` 45 | 46 | Similarly, POST data can be sent via curl; for example to test creating an alert via the dynamic alerts endpoint: 47 | 48 | ```bash 49 | $ curl -d 'json={"name": "JSONALERT", "description": "Dynamic alert added at runtime", "throttle": "10/min", "burst": "1/sec"}' http://username:password@localhost:2501/alerts/definitions/define_alert.cmd 50 | ``` 51 | 52 | which passes the parameters in the `json=` variable, and the login and password in the URI (username:password in this example). 53 | 54 | ### Exploring websockets 55 | 56 | Websockets are still a relatively new option in general, and are extremely new in Kismet. 57 | 58 | The easiest tool to interact with websockets for exploration is [websocat](https://github.com/vi/websocat) which gives a netcat-style interface to websockets. 59 | 60 | ```bash 61 | dragorn@lithium ~ % websocat 'ws://host:2501/eventbus/events.ws?user=username&password=password' 62 | {"SUBSCRIBE": "TIMESTAMP"} 63 | {"TIMESTAMP": {"kismet.system.timestamp.usec": 671986,"kismet.system.timestamp.sec": 1603120458}} 64 | {"TIMESTAMP": {"kismet.system.timestamp.usec": 672945,"kismet.system.timestamp.sec": 1603120459}} 65 | ``` 66 | 67 | ### What do all the fields mean? 68 | 69 | More information about each field can be found in the `/system/tracked_fields.html` URI by visiting `http://username:password@localhost:2501/system/tracked_fields.html` in your browser. This will show the field names, descriptions, and data types, for every known entity. 70 | 71 | ### Additional pretty-printed output 72 | 73 | For even more information, almost every REST endpoint can be requested using the `{foo}.prettyjson` format; this JSON output is styled for ease of readability and includes additional metadata to help understand the format; for example: 74 | 75 | ``` 76 | $ curl http://username:password@localhost:2501/system/status.prettyjson 77 | { 78 | "description.kismet.device.packets_rrd": "string, RRD of total packets seen", 79 | "kismet.device.packets_rrd": 80 | { 81 | "description.kismet.common.rrd.last_time": "uint64_t, last time udpated", 82 | "kismet.common.rrd.last_time": 1506473162, 83 | ... 84 | "description.kismet.system.battery.percentage": "int32_t, remaining battery percentage", 85 | "kismet.system.battery.percentage": 96, 86 | 87 | "description.kismet.system.battery.charging": "string, battery charging state", 88 | "kismet.system.battery.charging": "discharging", 89 | 90 | "description.kismet.system.battery.ac": "uint8_t, on AC power", 91 | "kismet.system.battery.ac": 0, 92 | 93 | "description.kismet.system.battery.remaining": "uint32_t, battery remaining in seconds", 94 | "kismet.system.battery.remaining": 0, 95 | 96 | "description.kismet.system.timestamp.sec": "uint64_t, system timestamp, seconds", 97 | "kismet.system.timestamp.sec": 1506473162, 98 | } 99 | } 100 | ``` 101 | 102 | For each defined field, Kismet will include a metadata field, `description.whatever.field.name`, which gives the type (for instance, uint32_t for a 32bit unsigned int), and the description, for instance 'battery remaining in seconds'. 103 | 104 | While the `prettyjson` format is well suited for learning about Kismet and developing tools to interface with the REST API, the `json` format should be used for final code; it is significantly faster than `prettyjson` and is optimized for processing time and space. 105 | 106 | `prettyjson` should work with nearly all REST endpoints which return JSON records, but will *NOT* work with `ekjson`-only endpoints (which are relatively rare, and documented accordingly below in the REST docs). 107 | 108 | ## Websockets 109 | 110 | *Added 2020-10* Kismet now supports websockets for long-running push-enabled communication. These can be explored with a Javascript environment, a tool like `wosocat`, or with support libraries in your preferred language. 111 | 112 | -------------------------------------------------------------------------------- /devel/rest/010-serialization.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Serialization types" 3 | permalink: /docs/devel/webui_rest/serialization/ 4 | docgroup: "devel-rest" 5 | excerpt: "Data can be serialized in several different ways, as traditional JSON, streaming pseudo-JSON for large queries, and as 'pretty' output for learning the API." 6 | --- 7 | ## Serialization Types 8 | 9 | Kismet can export data as several different formats; generally these formats are indicated by the type of endpoint being requested (such as foo.json) 10 | 11 | ### JSON 12 | 13 | Kismet will export objects in traditional JSON format suitable for consumption in javascript or any other language with a JSON interpreter. 14 | 15 | ### EKJSON 16 | 17 | "EK" JSON is modeled after the Elastic Search JSON format, where a complete JSON object is found on each line of the output. 18 | 19 | Kismet supports ekjson on any REST endpoint which returns a vector/list/array of results. 20 | 21 | *Added 2019-10* 22 | To be compatible with the ELK interpretation of field names, Kismet now permutes all field names in `ekjson` output, replacing all instances of `.` with `_`. 23 | 24 | ### ITJSON 25 | 26 | *Added 2019-10* 27 | 28 | "IT" or "Iterative" JSON is a variant of JSON optimized for large vector/array data sets. Instead of containing the entire output in a JSON array, each element of the array is sent on its own newline. 29 | 30 | *All non-ELK use of previous ekjson endpoints should now use itjson endpoints*. The ekjson serialization now modifies field names. 31 | 32 | Kismet supports itjson on any REST endpoint which returns a vector/list/array of results. 33 | 34 | The itjson results must be parsed *as a stream* instead of *as a traditional JSON object*. Attempting to parse an itjson response as traditional JSON will result in syntax errors. 35 | 36 | ### PRETTYJSON 37 | 38 | "Pretty" JSON is optimized for human readability and includes metadata fields describing what Kismet knows about each field in the JSON response. For more information, see the previous section, `Exploring the REST system`. 39 | 40 | "Pretty" JSON should only be used for learning about Kismet and developing; for actual use of the REST API standard "JSON" or "EKJSON" endpoints should be used as they are significantly faster and optimized. 41 | -------------------------------------------------------------------------------- /devel/rest/020-commands.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Commands" 3 | permalink: /docs/devel/webui_rest/commands/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Commands (actionable API calls) use a common method for defining arguments and options." 7 | --- 8 | 9 | Commands are sent via HTTP POST. Command options are sent as a JSON dictionary object in the POST field `json` 10 | 11 | This may be subject to change as the HTTP interface evolves. 12 | 13 | Commands should always be sent using the `x-www-form-encoded` content type; if your API does not do this by default, you may need to specify: 14 | 15 | ```javascript 16 | Content-Type: application/x-www-form-urlencoded; charset=utf-8 17 | ``` 18 | 19 | as part of the requests you send. 20 | 21 | Command dictionaries should be sent as a JSON dictionary in the `json` POST variable. 22 | 23 | ### Generating commands 24 | 25 | A simple Javascript generator might look similar to: 26 | 27 | ```javascript 28 | var json = { 29 | "cmd": "lock", 30 | "channel": "6", 31 | "uuid": "aaa:bbb:cc:dd:ee:ff:gg" 32 | }; 33 | 34 | var postdata = "json=" + JSON.stringify(json); 35 | 36 | $.post("/some/endpoint", data = postdata, dataType = "json"); 37 | ``` 38 | 39 | Similarly, commands can be sent from the command line: 40 | ```bash 41 | $ curl -d 'json={"cmd": "lock", "channel": 6}' http://host:port/some/endpoint 42 | ``` 43 | 44 | Commands are encoded as dictionaries to allow flexibility across calling platforms, as well as forward-compatibility as endpoints evolve. Adding additional keys to an options dictionary should not cause an older version of the server code to return an error. 45 | 46 | Dictionary key values are case sensitive. 47 | 48 | ### Timestamps 49 | 50 | Kismet allows both absolute and relative timestamps in almost all APIs which accept a timestamp value; those APIs which only work with an absolute timestamp will be denoted specially. 51 | 52 | An absolute timestamp value is a Unix timestamp in seconds since the timestamp epoch. All positive timestamp values are interpreted as absolute, epochal timestamps. 53 | 54 | A relative timestamp is calculated automatically by the Kismet server as relative from *now*. All negative timestamp values are interpreted as relative timestamps, and interpreted as (*now* - *timestamp*). 55 | 56 | Relative timestamps are useful for fetching events from the past *N* seconds, without needing to know the current timestamp of the server. 57 | 58 | ### Field Specifications 59 | 60 | Most endpoints which return records will also accept a field specification as part of the command dictionary. Field specifications allow the simplification of the data being returned, analogous to `select a, b, c` instead of `select *` in SQL. 61 | 62 | Simplifying fields, especially when performing very large queries, reduces the CPU and memory requiremets of Kismet *and* the client by reducing the amount of data being serialized, transmitted, and deserialized. Users of the REST API are *strongly* encouraged to make use of field simplification whenever plausible. 63 | 64 | Field specification objects take the format of a vector/array containing multiple field definitions: 65 | 66 | ```python 67 | [ 68 | field1, 69 | ... 70 | fieldN 71 | ] 72 | ``` 73 | 74 | where a field may be a single element string, defining a field name or a field path, such as: 75 | 76 | * `'kismet.device.base.channel'` 77 | * `'kismet.device.base.signal/kismet.common.signal.last_signal'` 78 | 79 | *or* a field may be a two-element array, consisting of a field name or path, and a target name the field will be aliased as, for example: 80 | 81 | * `['kismet.device.base.channel', 'base.channel']` 82 | * `['kismet.device.base.signal/kismet.common.signal.last_signal', 'base.last.signal']` 83 | 84 | Fields will be returned in the device as their final path name: that is, from the above example, the device would contain: 85 | 86 | `['kismet.device.base.channel', 'kismet.common.signal.last_signal']` 87 | 88 | And from the second example, it would contain: 89 | 90 | `['base.channel', 'base.last.signal']` 91 | 92 | When requesting multiple fields from different paths with the same name - for instance, multiple signal paths provide the `kismet.common.signal.last_signal` - it is important to provide an alias. Fields which resolve to the same name will only be present in the results once, and the order is undefined. 93 | 94 | #### Unknown fields 95 | 96 | Requesting a field which does not exist, or a path which cannot be resolved, will return a field of the requested name containing an integer `0`; for safety, consumers of the API should handle this gracefully. 97 | 98 | ### Regex filters 99 | 100 | Some endpoints in Kismet take a regex object. These endpoints use a common format, which allows for multiple regular expressions to be mapped to multiple fields. A device is considered to match if *any* of the regular expression terms are true. 101 | 102 | If the Kismet server was compiled *without* libpcre support, passing a regular expression to an endpoint will cause the endpoint to return an error. 103 | 104 | ```python 105 | [ 106 | [ multifield, regex ], 107 | ... 108 | [ multifield, regex ] 109 | ] 110 | ``` 111 | 112 | #### `multifield` 113 | 114 | `multifield` is a standard field path, but it will be automatically expanded to match all values if a vector or value-map field is encountered in the path. For example, the multifield path: 115 | 116 | `'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid'` 117 | 118 | will be expanded to include all `dot11.advertisedssid` objects in the `advetised_ssid_map` dictionary, and will apply to the `dot11.advertisedssid.ssid` field in each. Similarly, vectors, intmaps, doublemaps, macmaps, and so forth will be expanded, allowing matching against nested fields. 119 | 120 | The field is expected to resolve as a string: if it is not a string, the regex will be considered to not match. 121 | 122 | #### `regex` 123 | 124 | `regex` is a simple string containing a PCRE-compatible regular expression. 125 | 126 | #### Example 127 | 128 | For example, to match on SSIDs, a regex object might be: 129 | 130 | ```python 131 | regex = [ 132 | [ 'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid', '^SomePrefix.*' ], 133 | [ 'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid', '^Linksys$' ] 134 | ] 135 | ``` 136 | 137 | For extracting over curl, a similar example: 138 | 139 | ```bash 140 | $ curl -d \ 141 | 'json={"regex": [["dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid", "^Linksys$"]]}' \ 142 | http://user:password@server:2501/devices/views/phydot11_accesspoints/devices.json 143 | ``` 144 | 145 | #### Array of regex pairs 146 | 147 | Notice that the regex field takes an *array* of field/regex pairs! For a single regex match, the nested array is still required: 148 | 149 | ``` 150 | json={"regex": [ ["field", "match"] ]} 151 | ``` 152 | 153 | *not* 154 | 155 | ``` 156 | json={"regex": ["broken", "example"]} 157 | ``` 158 | 159 | 160 | -------------------------------------------------------------------------------- /devel/rest/021-keys_and_macs.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Keys and MAC addresses" 3 | permalink: /docs/devel/webui_rest/keys_and_macs/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "The differences between keys and macs, and optional MAC group matching." 7 | --- 8 | 9 | ## MAC addresses 10 | 11 | The MAC address is a theoretically unique identifier given to a device at manufacture time. For Ethernet and Wi-Fi devices, this is assigned by the IEEE, and must be unique. 12 | 13 | Typically a MAC address is 6 bytes. Kismet supports MAC addresses up to 8 bytes, however no PHYs currently use these. 14 | 15 | Kismet will attempt to synthesize MAC addresses for PHYs which do not present traditional MAC addresses. 16 | 17 | ## Keys 18 | 19 | Kismet uses a unique key for each device. The key is *derived from* the MAC address, but contains additional information about the PHY type. This allows multiple devices to have the same MAC address under different PHY types without overlap; this can be of particular importance when using non-traditional PHY types which do not use strict device identifiers. 20 | 21 | ## MAC address masking 22 | 23 | On queries and filters affecting MAC addresses, Kismet supports complete addresses or partial addresses with masking. 24 | 25 | A masked address resembles the syntax typically used for IP network masking: `[MAC]/[MASK]`. 26 | 27 | For instance, to match only the OUI, a masked MAC of: 28 | 29 | ```json 30 | "aa:bb:cc:00:00:00/ff:ff:ff:00:00:00" 31 | ``` 32 | 33 | This would match any MAC address where the OUI, or first three bytes, are "aa:bb:cc". A similar feature to match on the first *four* bytes would be: 34 | 35 | ```json 36 | "aa:bb:cc:dd:00:00/ff:ff:ff:ff:00:00" 37 | ``` 38 | 39 | -------------------------------------------------------------------------------- /devel/rest/030-system.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "System status" 3 | permalink: /docs/devel/webui_rest/system_status/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Basic system status and health reporting." 7 | --- 8 | 9 | ## System status 10 | 11 | * URL 12 | 13 | /system/status.json 14 | 15 | * Methods 16 | 17 | `GET` `POST` 18 | 19 | * Role 20 | 21 | `readonly` 22 | 23 | Errata: Incorrectly marked as `logon` in 2020-R1 24 | 25 | * POST parameters 26 | 27 | | Key | Description | 28 | | --- | ----------- | 29 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 30 | 31 | * Result 32 | 33 | Dictionary of Kismet system-level status, including update, battery, memory, and thermal data, optionally simplified. 34 | 35 | ## Timestamp 36 | 37 | * URL 38 | 39 | /system/timestamp.json 40 | 41 | * Methods 42 | 43 | `GET` 44 | 45 | * Role 46 | 47 | `readonly` 48 | 49 | Errata: Incorrectly marked as `logon` in 2020-R1 50 | 51 | * Result 52 | 53 | Dictionary of system timestamp as second, microsecond; can be used to synchronize timestamps and as a keep-alive check. 54 | 55 | ## Tracked fields 56 | 57 | * URL 58 | 59 | /system/tracked_fields.html 60 | 61 | * Methods 62 | 63 | `GET` 64 | 65 | * Role 66 | 67 | `readonly` 68 | 69 | * Result 70 | 71 | Human-readable table of all registered field names, types, and descriptions. While it cannot represent the nested features of some data structures, it will describe every allocated field. This endpoint returns a HTML document for ease of use. 72 | 73 | ## Packet counts 74 | 75 | * URL 76 | 77 | /packetchain/packet_stats.json 78 | 79 | * Methods 80 | 81 | `GET` `POST` 82 | 83 | * Role 84 | 85 | `readonly` 86 | 87 | * POST parameters 88 | 89 | | Key | Description | 90 | | --- | ----------- | 91 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 92 | 93 | * Result 94 | 95 | Dictionary of packet rate RRDs for various packet queues 96 | 97 | ## Dynamic javascript include 98 | 99 | Kismet provides a dynamically generated javascript file which is loaded by the UI, which in turn loads the core system and plugin JS modules. 100 | 101 | * URL 102 | 103 | /dynamic.js 104 | 105 | * API Added 106 | 107 | `2022-01` 108 | 109 | * Methods 110 | 111 | `GET` 112 | 113 | * Role 114 | 115 | `readonly` 116 | 117 | * Result 118 | 119 | This returns a full javascript file which in turn loads the JS modules registered with Kismet and inserts them into the global namespace. It should be included as a script file in the UI, such as: 120 | 121 | ```html 122 | 123 | ``` 124 | 125 | -------------------------------------------------------------------------------- /devel/rest/031-eventbus.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Eventbus socket" 3 | permalink: /docs/devel/webui_rest/eventbus/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Event bus socket" 7 | --- 8 | 9 | ## Eventbus 10 | 11 | The `event bus` is a push/publish system inside Kismet where events are transmitted. Events contain a `string:object` dictionary of values and content, and can contain simple data or complete Kismet objects. 12 | 13 | The eventbus API is a websocket endpoint with a subscription model for attaching an UI to the eventbus. Events are sent over the socket automatically from the Kismet server. 14 | 15 | In the standard web UI, Kismet combines the poll APIs to populate the initial pre-existing data (such as alerts, message text, and so on), then subscribes to the eventbus socket to receive updates as push events. 16 | 17 | Eventbus topics are case-sensitive, and for topics which contain Kismet objects, the returned JSON is formatted using Kismet field names and types and is identical to the records returned via polling APIs. 18 | 19 | * URL 20 | 21 | /eventbus/events.ws 22 | 23 | * API Added 24 | 25 | `2020-10` 26 | 27 | * Methods 28 | 29 | `WEBSOCKET` (HTTP Upgrade + Websocket handshake) 30 | 31 | * Role 32 | 33 | `readonly` 34 | 35 | * URI parameters 36 | 37 | | Key | Description | 38 | | --- | ----------- | 39 | | user | Kismet administrative username, as HTTP URI-encoded variable | 40 | | password | Kismet administrative password, as HTTP URI-encoded variable | 41 | | KISMET | Kismet auth cookie, as HTTP URI-encoded variable | 42 | 43 | * Result 44 | 45 | A websocket session with a subscription-model API 46 | 47 | * Notes 48 | 49 | 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. 50 | 51 | Some tools (websocat, others) allow sending HTTP basic auth as part of the URI (`ws://user:pass@host:port/eventbus/events.ws`). However, modern browser implementations do *not* support this, and websockets must be constructed using GET parameters, such as `ws://host:port/eventbus/events.ws?user=username&password=userpass`. 52 | 53 | Websocket URIs *must* match the content type of the calling page; a `https` page must use the `wss` URI and a `http` page must use the `ws` URI. The Kismet UI detects this via javascript. 54 | 55 | ## Eventbus subscription API 56 | 57 | The eventbus subscription API accepts JSON data requesting a subscription topic and optional [field simplification](/docs/devel/webui_rest/commands/#field-specifications). 58 | 59 | Currently consumers are limited to *one* subscription *per topic*; it is not possible for a single connection to subscribe to the same topic twice with different field selections. Multiple websocket connections from the same client may subscribe to the same topic with different field selections without restriction, however. 60 | 61 | An eventbus JSON command contains: 62 | 63 | | Key | Content | 64 | | --- | ----------- | 65 | | SUBSCRIBE | Topic to subscribe to, case sensitive | 66 | | UNSUBSCRIBE | Topic to unsubscribe from, case sensitive | 67 | | fields | If subscribing, a standard [field simplification](/docs/devel/webui_rest/commands/#field-specificiations) | 68 | 69 | Either a `SUBSCRIBE` or `UNSUBSCRIBE` must be provided with each command. 70 | 71 | Once subscribed to a topic, an eventbus receiver will be sent a websocket text message containing the JSON record for each event which matches that subscription, optionally simplified. 72 | 73 | For instance: 74 | 75 | ```bash 76 | dragorn@lithium ~ % websocat 'ws://host:2501/eventbus/events.ws?user=username&password=password' 77 | {"SUBSCRIBE": "TIMESTAMP"} 78 | {"TIMESTAMP": {"kismet.system.timestamp.usec": 671986,"kismet.system.timestamp.sec": 1603120458}} 79 | {"TIMESTAMP": {"kismet.system.timestamp.usec": 672945,"kismet.system.timestamp.sec": 1603120459}} 80 | ``` 81 | 82 | Or in Javascript: 83 | 84 | ```javascript 85 | var ws = new Websocket('ws://host:2501/eventbus/events.ws?user=username&password=password'); 86 | ws.onmessage = function(msg) { 87 | var json = JSON.parse(msg.data); 88 | console.log(json); 89 | } 90 | ws.onopen = function(event) { 91 | var req = { 92 | "SUBSCRIBE": "TIMESTAMP" 93 | } 94 | ws.send(JSON.stringify(req)); 95 | } 96 | ``` 97 | 98 | ## Eventbus topics 99 | 100 | Eventbus topics may be dynamically expanded by plugins, external helper tools, and more. Some topics are used predominately as internal messaging mechanisms between components of Kismet, while others are generated at regular intervals specifically for consumption by external UI and monitoring systems. 101 | 102 | Event topics include: 103 | 104 | ### ALERT 105 | 106 | * Content 107 | 108 | JSON object containing a Kismet alert record 109 | 110 | * Generation 111 | 112 | Published whenever an alert is raised in the Kismet WIDS/Alert system 113 | 114 | ### BATTERY 115 | 116 | * Content 117 | 118 | JSON object containing the battery presence, charge, and rate data, as per the system statistics API 119 | 120 | * Generation 121 | 122 | Published once per second by the Kismet server 123 | 124 | ### DATASOURCE_PAUSED 125 | 126 | * Content 127 | 128 | 129 | * Generation 130 | 131 | Published when a running datasource is paused 132 | 133 | ### DATASOURCE_RESUMED 134 | 135 | * Content 136 | 137 | JSON object containing a Kismet datasource record 138 | 139 | * Generation 140 | 141 | Published when a paused datasource is resumed 142 | 143 | ### DATASOURCE_ERROR 144 | 145 | * Content 146 | 147 | The UUID of a Kismet datasource 148 | 149 | * Generation 150 | 151 | Published when a datasource experiences an error 152 | 153 | ### DATASOURCE_OPENED 154 | 155 | * Content 156 | 157 | The UUID of a Kismet datasource 158 | 159 | * Generation 160 | 161 | Published when a datasource is opened (or re-opened) 162 | 163 | ### DATASOURCE_CLOSED 164 | 165 | * Content 166 | 167 | The UUID of a Kismet datasource 168 | 169 | * Generation 170 | 171 | Published when a datasource is closed 172 | 173 | ### DOT11_ADVERTISED_SSID 174 | 175 | * Content 176 | 177 | Contains 2 keys, DOT11_NEW_SSID_BASEDEV and DOT11_ADVERTISED_SSID, which contain, respectively, the base Kismet device complete record, and the new SSID sub-record. 178 | 179 | * Generation 180 | 181 | Published when a new advertised (via beacons) SSID is discovered 182 | 183 | ### DOT11_RESPONSE_SSID 184 | 185 | * Content 186 | 187 | Contains 2 keys, DOT11_NEW_SSID_BASEDEV and DOT11_RESPONSE_SSID, which contain, respectively, the base Kismet device complete record, and the new SSID sub-record. 188 | 189 | * Generation 190 | 191 | Published when an access point responds to a SSID for the first time (vie probe responses), per BSSID. 192 | 193 | ### DOT11_PROBED_SSID 194 | 195 | * Content 196 | 197 | Contains 2 keys, DOT11_NEW_SSID_BASEDEV and DOT11_PROBED_SSID, which contain, respectively, the base Kismet device complete record, and the new SSID sub-record. 198 | 199 | * Generation 200 | 201 | Published when a device probes for a SSID the first time, per device MAC 202 | 203 | ### DOT11_WPA_HANDSHAKE 204 | 205 | * Content 206 | 207 | Contains two keys, DOT11_WPA_HANDSHAKE_BASEDEV and DOT11_WPA_HANDSHAKE_DOT11, which contain, respectively, the base Kismet device and the 802.11-specific device sub-record. 208 | 209 | * Generation 210 | 211 | Published when a complete (or estimated to be complete) WPA handshake is captured 212 | 213 | ### GPS_LOCATION 214 | 215 | * Content 216 | 217 | JSON object containing the current 'best' GPS location, as per the GPS location API 218 | 219 | * Generation 220 | 221 | Published once per second by the Kismet server 222 | 223 | ### KISMETDB_LOG_OPEN 224 | 225 | * Content 226 | 227 | None 228 | 229 | * Generation 230 | 231 | Published when the kismetdb log is successfully opened 232 | 233 | ### MESSAGE 234 | 235 | * Content 236 | 237 | JSON object containing a Kismet messagebus message (text, flags, and timestamp) 238 | 239 | * Generation 240 | 241 | Published when a new message is generated in Kismet 242 | 243 | ### NEW_DATASOURCE 244 | 245 | * Content 246 | 247 | JSON object containing a Kismet datasource record 248 | 249 | * Generation 250 | 251 | Published when a new datasource is defined 252 | 253 | ### PACKETCHAIN_STATS 254 | 255 | * Content 256 | 257 | JSON object containing the packet chain statistics RRDs, as per the packetchain stats API 258 | 259 | * Generation 260 | 261 | Published once per second by the Kismet server 262 | 263 | ### TIMESTAMP 264 | 265 | * Content 266 | 267 | JSON object containing the second and usecond timestamp 268 | 269 | * Generation 270 | 271 | Published automatically once per second by the Kismet server 272 | 273 | -------------------------------------------------------------------------------- /devel/rest/040-device_views.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Device views" 3 | permalink: /docs/devel/webui_rest/device_views/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "A common 'device view' API which is used by many components of Kismet to present different views of the device data while retaining identical API calls." 7 | --- 8 | 9 | ## Device views 10 | 11 | Device views are optimized subsets of the global device list. Device views can be defined by PHY handlers, plugins, as part of the base Kismet code, or user-supplied data. 12 | 13 | All device views respond to the same common API; any code which access a specific device view should be portable across multiple views. 14 | 15 | ### View list 16 | 17 | The view list shows all defined device views and a summary of the number of devices in each. 18 | 19 | * URL 20 | 21 | /devices/views/all_views.json 22 | 23 | /devices/views/all_views.ekjson 24 | 25 | /devices/views/all_views.itjson 26 | 27 | * Methods 28 | 29 | `GET` 30 | 31 | * Role 32 | 33 | `readonly` 34 | 35 | * Results 36 | 37 | Array of device views and device counts per view. 38 | 39 | ### View-based summarization and display 40 | 41 | Mirroring the [base summarization & display endpoint](/docs/devel/webui_rest/devices/#old-summarization--display) API, the view summarization endpoint is the primary interface for clients to access the device list and for scripts to retrieve lists of devices. 42 | 43 | The device summarization is best utilized when applying a view window via the `start` and `length` variables. 44 | 45 | * URL 46 | 47 | /devices/views/*[VIEWID]*/devices.json 48 | 49 | * Methods 50 | 51 | `POST` 52 | 53 | * Role 54 | 55 | `readonly` 56 | 57 | * URL parameters 58 | 59 | | Key | Description | 60 | | --- | ----------- | 61 | | *[VIEWID]* | Kismet view ID | 62 | 63 | * POST parameters 64 | 65 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 66 | 67 | | Key | Description | 68 | | ------- | ----------------------------------------------------- | 69 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 70 | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | 71 | | colmap | Optional, inserted by the Kismet Datatable UI for mapping column information for proper ordering and sorting. | 72 | | 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. | 73 | 74 | Additionally, when in datatables mode, the following HTTP POST variables are used: 75 | 76 | | Key | Description | 77 | | --- | ---- | 78 | | start | Data view window start position | 79 | | length | Datatable window end | 80 | | draw | Datatable draw value | 81 | | search[value] | Search term, applied to all fields in the summary vector | 82 | | order\[0\]\[column\] | Display column number for sorting, indexed with colmap data | 83 | | order\[0\]\[dir\] | Sort order direction from jquery-datatables | 84 | 85 | * Results 86 | 87 | Summarized array of devices. 88 | 89 | ### Devices by view & time 90 | 91 | Mirroring the [Activity & timestamp](/docs/devel/webui_rest/devices/#activity--timestamp) API, fetches devices from a specified view which have been active since the supplied timestamp. This endpoint is typically used by scripted clients to monitor active devices within a view. 92 | 93 | * URL 94 | 95 | /devices/views/*[VIEWID]*/last-time/*[TIMESTAMP]*/devices.json 96 | 97 | /devices/views/*[VIEWID]*/last-time/*[TIMESTAMP]*/devices.ekjson 98 | 99 | /devices/views/*[VIEWID]*/last-time/*[TIMESTAMP]*/devices.itjson 100 | 101 | * Methods 102 | 103 | `GET` `POST` 104 | 105 | * Role 106 | 107 | `readonly` 108 | 109 | * URL parameters 110 | 111 | | Key | Description | 112 | | --- | ----------- | 113 | | *[VIEWID]* | Kismet view ID | 114 | | *[TIMESTAMP]* | Relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | 115 | 116 | * POST parameters 117 | 118 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 119 | 120 | | Key | Description | 121 | | --- | ----------- | 122 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 123 | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | 124 | 125 | * Results 126 | 127 | Array of devices in view *VIEWID* with activity more recent than *TIMESTAMP* with optional field simplification. 128 | 129 | 130 | ### Realtime device monitoring by view 131 | 132 | Mirroring the [Realtime device monitoring](/docs/devel/webui_rest/devices/#realtime-device-monitoring) API, provides a subscription-based realtime push API for monitoring devices within a view. 133 | 134 | 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. 135 | 136 | * URL 137 | 138 | /devices/views/*[VIEWID]*/monitor.ws 139 | 140 | * API added 141 | 142 | `2021-01` 143 | 144 | * Methods 145 | 146 | `WEBSOCKET` (HTTP Upgrade + Websocket handshake) 147 | 148 | * Role 149 | 150 | `readonly` 151 | 152 | * URI parameters 153 | 154 | | Key | Description | 155 | | --- | ----------- | 156 | | *[VIEWID]* | Kismet view ID | 157 | | user | Kismet administrative username, as HTTP URI-encoded variable | 158 | | password | Kismet administrative password, as HTTP URI-encoded variable | 159 | | KISMET | Kismet auth cookie, as HTTP URI-encoded variable | 160 | 161 | * Result 162 | 163 | A websocket session with a subscription-model API 164 | 165 | HTTP error on failure 166 | 167 | * Notes 168 | 169 | 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. 170 | 171 | The subscription and result API is [identical to the device monitoring API](/docs/devel/webui_rest/devices/#realtime-device-monitoring) API 172 | 173 | -------------------------------------------------------------------------------- /devel/rest/045-messages.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Messages" 3 | permalink: /docs/devel/webui_rest/messages/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Kismet exposes the console messages via the messagebus API." 7 | --- 8 | 9 | Kismet uses an internal `messagebus` system for communicating text messages from system components to the user. The messagebus is used to pass error, state, and debug messages, as well as notifications to the user about detected devices, alerts, etc. 10 | 11 | For real-time message data, see the [eventbus](/docs/devel/webui_rest/eventbus/). 12 | 13 | ## All messages 14 | 15 | * URL 16 | 17 | /messagebus/all_messages.json 18 | 19 | /messagebus/all_messages.ekjson 20 | 21 | /messagebus/all_messages.itjson 22 | 23 | * Methods 24 | 25 | `GET` 26 | 27 | * Role 28 | 29 | `readonly` 30 | 31 | * Result 32 | 33 | Array of the last 50 messages in the messagebus 34 | 35 | ## Recent messages 36 | 37 | * URL 38 | 39 | /messagebus/last-time/*[TIMESTAMP]*/messages.json 40 | 41 | /messagebus/last-time/*[TIMESTAMP]*/messages.ekjson 42 | 43 | /messagebus/last-time/*[TIMESTAMP]*/messages.itjson 44 | 45 | * Methods 46 | 47 | `GET` 48 | 49 | * Role 50 | 51 | `readonly` 52 | 53 | * URL parameters 54 | 55 | | Key | Description | 56 | | --- | ----------- | 57 | | *[TIMESTAMP]* | Relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | 58 | 59 | * Result 60 | 61 | Array of messages since *TIMESTAMP* 62 | 63 | -------------------------------------------------------------------------------- /devel/rest/055-channels.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Channels" 3 | permalink: /docs/devel/webui_rest/channels/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Observed channels and channel traffic API." 7 | --- 8 | 9 | ## Channels 10 | 11 | * URL 12 | 13 | /channels/channels.json 14 | 15 | /channels/channels.ekjson 16 | 17 | /channels/channels.itjson 18 | 19 | * Methods 20 | 21 | `GET` 22 | 23 | * Role 24 | 25 | `readonly` 26 | 27 | * Result 28 | 29 | Dictionary containing channel usage, device counts, and coverage data. 30 | 31 | -------------------------------------------------------------------------------- /devel/rest/070-packet_capture.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Packet capture" 3 | permalink: /docs/devel/webui_rest/packet_capture/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Access the packet stream live with optional datasource and device filtering." 7 | --- 8 | Kismet can export packets in the pcap-ng format; this is a standard, extended version of the traditional pcap format. Tools such as Wireshark (and tshark) can process complete pcapng frames, while tcpdump and other libpcap based tools (currently including Kismet) can process the simpler version of pcapng. 9 | 10 | The pcap-ng format allows for multiple interfaces and linktypes to be stored in a single file. This format can be read and processed by [Wireshark and tshark](https://www.wireshark.org) but may not be compatible with all traditional libpcap-based tools. Typically, libpcap based tools can easily process a pcap-ng file with a *single source* but may have difficulty processing files with multiple sources. 11 | 12 | The pcap-ng file can be post-processed with `tshark` or `wireshark` to strip it to a single interface if necessary. 13 | 14 | ## All packets 15 | 16 | Kismet can provide a live stream, in pcap-ng format, of all packets *since the time of this request* seen by Kismet from all datasources. 17 | 18 | To access packets *previously seen* by Kismet, look at the [kismetdb endpoints](/docs/devel/webui_rest/kismetdb/). 19 | 20 | * URL 21 | 22 | /pcap/all_packets.pcapng 23 | 24 | * Methods 25 | 26 | `GET` 27 | 28 | * Role 29 | 30 | `readonly` 31 | 32 | * Results 33 | 34 | A pcap-ng stream of packets which will stream indefinitely as packets are received. 35 | 36 | ## Packets by datasource 37 | 38 | The packet stream may be limited to packets captured by a single datasource, indicated by the datasource UUID. 39 | 40 | * URL 41 | 42 | /datasource/pcap/by-uuid/*[UUID]*/packets.pcapng 43 | 44 | * Methods 45 | 46 | `GET` 47 | 48 | * Role 49 | 50 | `readonly` 51 | 52 | * URL parameters: 53 | 54 | | Key | Description | 55 | | --- | ----------- | 56 | | *[UUID]* | Datasource UUID | 57 | 58 | * Results 59 | 60 | A pcap-ng stream of packets which will stream indefinitely as packets are received. 61 | 62 | ## Packets by device 63 | 64 | The packet stream may be limited to packets captured and associated with a specific device by Kismet, indicated by the Kismet device key. 65 | 66 | * URL 67 | 68 | /devices/pcap/by-key/*[KEY]*/packets.pcapng 69 | 70 | * Methods 71 | 72 | `GET` 73 | 74 | * Role 75 | 76 | `readonly` 77 | 78 | * URL parameters: 79 | 80 | | Key | Description | 81 | | --- | ----------- | 82 | | *[KEY]* | Device key | 83 | 84 | * Results 85 | 86 | A pcap-ng stream of packets which will stream indefinitely as packets are received. 87 | 88 | -------------------------------------------------------------------------------- /devel/rest/075-plugins.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Plugins" 3 | permalink: /docs/devel/webui_rest/plugins/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Information about running Kismet plugins." 7 | --- 8 | Kismet plugins may be active C++ code (loaded as a plugin.so shared object file) or they may be web content only which is loaded into the UI without requiring additional back-end code. 9 | 10 | ## Plugin list 11 | 12 | * URL 13 | 14 | /plugins/all_plugins.json 15 | 16 | /plugins/all_plugins.ekjson 17 | 18 | /plugins/all_plugins.itjson 19 | 20 | * Methods 21 | 22 | `GET` 23 | 24 | * Role 25 | 26 | `readonly` 27 | 28 | * Results 29 | 30 | Returns array of activated plugins 31 | 32 | -------------------------------------------------------------------------------- /devel/rest/080-streams.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Streams" 3 | permalink: /docs/devel/webui_rest/streams/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Logging and long-running live exports of data are classified as streams and can be observed and manipulated via the stream API." 7 | --- 8 | A Kismet stream is linked to an export of data of prolonged length; for instance, packet capture logs to disk or streamed over the web API. 9 | 10 | Streams can be monitored and managed; a privileged user can close existing streams. 11 | 12 | ## Streams list 13 | 14 | * URL 15 | 16 | /streams/all_streams.json 17 | 18 | /streams/all_streams.ekjson 19 | 20 | /streams/all_streams.itjson 21 | 22 | * Methods 23 | 24 | `GET` 25 | 26 | * Role 27 | 28 | `readonly` 29 | 30 | * Result 31 | 32 | Array of active streams 33 | 34 | ## Stream details 35 | 36 | * URL 37 | 38 | /streams/by-id/*[STREAMID]*/stream_info.json 39 | 40 | * Methods 41 | 42 | `GET` 43 | 44 | * Role 45 | 46 | `readonly` 47 | 48 | * URL parameters 49 | 50 | | Key | Description | 51 | | --- | ----------- | 52 | | *[STREAMID]* | ID of stream to examine | 53 | 54 | * Results 55 | 56 | Returns detailed stream information object 57 | 58 | ## Closing a stream 59 | 60 | Closing a stream cancels any data being transferred or stored. 61 | 62 | * URL 63 | 64 | /streams/by-id/*[STREAMID]*/close_stream.cmd 65 | 66 | * Methods 67 | 68 | `GET` 69 | 70 | * Role 71 | 72 | `admin` 73 | 74 | * URL parameters 75 | 76 | | Key | Description | 77 | | --- | ----------- | 78 | | *[STREAMID]* | ID of stream to close | 79 | 80 | * Results 81 | 82 | `HTTP 200` on successful stream closure 83 | 84 | HTTP error on failure 85 | 86 | -------------------------------------------------------------------------------- /devel/rest/085-logging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Logging" 3 | permalink: /docs/devel/webui_rest/logging/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "View and control logging attributes live." 7 | --- 8 | Kismet uses a centralized logging architecture which manages enabling and tracking the status of logs. The logging system integrates with the [streaming sytem](/docs/devel/webui_rest/streams/) for long-running log files. 9 | 10 | ## Log drivers 11 | 12 | Log drivers handle a specific type of logfile. 13 | 14 | * URL 15 | 16 | /logging/drivers.json 17 | 18 | /logging/drivers.ekjson 19 | 20 | /logging/drivers.itjson 21 | 22 | * Methods 23 | 24 | `GET` 25 | 26 | * Role 27 | 28 | `readonly` 29 | 30 | * Result 31 | 32 | Array of supported log types 33 | 34 | ## Active logs 35 | 36 | Not all drivers are activated depending on the Kismet config optins. 37 | 38 | * URL 39 | 40 | /logging/active.json 41 | 42 | /logging/active.ekjson 43 | 44 | /logging/active.itjson 45 | 46 | * Methods 47 | 48 | `GET` 49 | 50 | * Role 51 | 52 | `readonly` 53 | 54 | * Result 55 | 56 | Array of activated logs. 57 | 58 | ## Enabling logs 59 | 60 | Logs can be enabled run-time. 61 | 62 | * URL 63 | 64 | /logging/by-class/*[LOGCLASS]*/start.cmd 65 | 66 | * Methods 67 | 68 | `GET` `POST` 69 | 70 | * Role 71 | 72 | `admin` 73 | 74 | * URL parameters 75 | 76 | | Key | Description | 77 | | --- | ----------- | 78 | | *[LOGCLASS]* | Kismet log class to enable | 79 | 80 | * POST parameters 81 | 82 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 83 | 84 | | Key | Description | 85 | | --- | ----------- | 86 | | title | Alternate log title, overriding the `kismet_logging.conf` config for `log_title=` | 87 | 88 | * Results 89 | 90 | `HTTP 200` and log object for newly created log on success 91 | 92 | HTTP error on failure 93 | 94 | ## Stopping logs 95 | 96 | Logs can be stopped run-time. The log must be open and running to be stopped. 97 | 98 | * URL 99 | 100 | /logging/by-uuid/*[LOGUUID]*/stop.cmd 101 | 102 | * Methods 103 | 104 | `GET` 105 | 106 | * Role 107 | 108 | `admin` 109 | 110 | * URL parameters 111 | 112 | | Key | Description | 113 | | --- | ----------- | 114 | | *[LOGUUID]* | Kismet log UUID to stop | 115 | 116 | * Results 117 | 118 | `HTTP 200` on success 119 | 120 | HTTP error on failure 121 | 122 | -------------------------------------------------------------------------------- /devel/rest/086-poi.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Points of interest" 3 | permalink: /docs/devel/webui_rest/poi/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Points-of-interest can be tagged live, allowing for integration of physical buttons or other scripts to make a kismetdb entry for future analysis." 7 | --- 8 | You can tag a time and location as a "point of interest" using the POI API. This API is only available when the `kismetdb` log is enabled. 9 | 10 | ## Create a POI 11 | 12 | A POI is entered in the `kismetdb` log file as a `snapshot` record of type `POI`. A POI will have the current GPS location and time, and an optional note. 13 | 14 | * URL 15 | 16 | /poi/create_poi.cmd 17 | 18 | * Methods 19 | 20 | `POST` 21 | 22 | * Role 23 | 24 | `admin` 25 | 26 | * API added 27 | 28 | `2019-03` 29 | 30 | * POST parameters 31 | 32 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 33 | 34 | | Key | Description | 35 | | --- | ----------- | 36 | | note | Optional human-readable 'note' to be added to the POI log. | 37 | 38 | * Results 39 | 40 | `HTTP 200` on success 41 | 42 | HTTP error on failure 43 | 44 | -------------------------------------------------------------------------------- /devel/rest/090-kismetdb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "KismetDB logs" 3 | permalink: /docs/devel/webui_rest/kismetdb/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Kismet stores all of its information in the kismetdb log; by exposing interfaces to the kismetdb log via the REST api, it becomes possible to access not only the current data and live packet streams, but previously captured packets and events." 7 | --- 8 | If the Kismet Databaselog is enabled, Kismet will expose an API for extracting historic data. If the databaselog is not enabled, these APIs will not be available and will return an error. 9 | 10 | ## Packet filtering 11 | The `filter` options in are treated as logical `AND` statements: To match a packet, the packet must match *all* of the filter options passed in the command dictionary. In other words, a filter by time, datasource, and type, would *only* return packets within that time range, from that datasource, and of that type. 12 | 13 | Filter options should be sent as GET parameters URL-encoded, when using the GET REST endpoint, and in a command dictionary under the `filter` key when using the POST endpoint. 14 | 15 | ### Filter options 16 | 17 | 1. Time window 18 | 19 | Packets can be selected by a time window which may either be closed (both start and end times specified) or open (only start or end time specified). 20 | 21 | | Key | Type | Description | 22 | | --------------- | ------ | ------------------------------------------------------------ | 23 | | timestamp_start | double | Posix timestamp as double-precision value (seconds.microseconds) | 24 | | timestamp_end | double | Posix timestamp as double-precision value (seconds.microseconds) | 25 | 26 | 2. Datasource 27 | 28 | Packets may be limited to a single data source, specified by UUID 29 | 30 | | Key | Type | Description | 31 | | ---------- | --------- | --------------------------------- | 32 | | datasource | text UUID | UUID string of capture datasource | 33 | 34 | 3. Kismet device 35 | 36 | Packets may be limited to the specific Kismet device ID they belong to 37 | 38 | | Key | Type | Description | 39 | | --------- | ------- | ---------------- | 40 | | device_id | text ID | Kismet device ID | 41 | 42 | 4. Data type 43 | Limit matching to a specific data type / DLT (Data Link Type). This numeric DLT matches the libpcap link types and describes the physical frame type of the packet. 44 | 45 | | Key | Type | Description | 46 | | ---- | ------- | ----------- | 47 | | dlt | integer | PCAP DLT | 48 | 49 | 5. Frequency 50 | 51 | Match only packets on the given frequency, if frequency information is available from the data source. Data sources which cannot report frequency will report as `0`. 52 | 53 | | Key | Type | Description | 54 | | --------- | ------ | ---------------- | 55 | | frequency | double | Frequency in KHz | 56 | | frequency_min | double | Minimum frequency in KHz | 57 | | frequency_max | double | Maximum frequency in KHz | 58 | 59 | 7. Signal window 60 | 61 | Limit matching to a range of signal levels, which may be open (only min/max signal provided) or closed (min and max specified). Packets which have no signal data (such as packets captured by source types which do not support signal records) will have a reported signal of `0`. 62 | 63 | | Key | Type | Description | 64 | | ---------- | ---- | ----------------------- | 65 | | signal_min | int | Minimum signal (in dBm) | 66 | | signal_max | int | Maximum signsl (in dBm) | 67 | 68 | 8. Device addresses 69 | 70 | Limit matching by decoded device address, if available. Not all capture phys report device addresses as MAC addresses, however the majority do. 71 | 72 | | Key | Type | Description | 73 | | -------------- | -------- | ---------------------------------------------- | 74 | | address_source | text MAC | Source MAC address | 75 | | address_dest | text MAC | Destination MAC address | 76 | | address_trans | text MAC | Transmitter MAC address (such as the AP BSSID) | 77 | 78 | 9. Location window 79 | 80 | Limit matching by location. Location windows should always be bounded rectangles of minimum and maximum coordinates. Coordinates are in decimal floating-point format (LL.LLLLL) and will be converted to the normalized non-floating internal values automatically. 81 | 82 | | Key | Type | Description | 83 | | ---------------- | ------ | ------------------------ | 84 | | location_lat_min | double | Minimum corner latitude | 85 | | location_lon_min | double | Minimum corner longitude | 86 | | location_lat_max | double | Maximum corner latitude | 87 | | location_lon_max | double | Maximum corner longitude | 88 | 89 | 10. Packet size window 90 | 91 | Limit matching by packet size. Size windows can define minimum and maximum or only minimum or maximum ranges. 92 | 93 | | Key | Type | Description | 94 | | -------- | ---- | ----------------------------- | 95 | | size_min | int | Minimum packet size, in bytes | 96 | | size_max | int | Maximum packet size, in bytes | 97 | 98 | 11. Tags 99 | 100 | Packets can be tagged with various state information. 101 | 102 | | Key | Type | Description | 103 | | -------- | ---- | ----------------------------- | 104 | | tag | string | Tag to limit by | 105 | 106 | 107 | 12. Result limiting 108 | 109 | Limit total packets returned. 110 | 111 | | Key | Type | Description | 112 | | -------- | ---- | ----------------------------- | 113 | | limit | int | Maximum results to return | 114 | 115 | ## Fetching historic packets 116 | 117 | Packets can be fetched from the `kismetdb`, for all packets stored in the current session `kismetdb` log. 118 | 119 | * URL 120 | 121 | /logging/kismetdb/pcap/*[TITLE]*.pcapng 122 | 123 | /logging/kismetdb/pcap/*[TITLE]*.pcapng?option1=...&option2=... 124 | 125 | * API added 126 | 127 | `2018-12` 128 | 129 | * Methods 130 | 131 | `GET` `POST` 132 | 133 | * URL parameters 134 | 135 | | Key | Description | 136 | | --- | ----------- | 137 | | *[TITLE]* | File download title, does not impact pcap file generation. | 138 | 139 | Additionally, when using the `GET` URI, the [filter options](#filter-options) defined above are accepted as `HTTP GET` URL-encoded variables. 140 | 141 | * POST parameters 142 | 143 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 144 | 145 | | Key | Description | 146 | | --- | ----------- | 147 | | filter | A dictionary of the [filter options](#filter-options) defined above | 148 | 149 | * Result 150 | 151 | `HTTP 500` error if the `kismet` log type is not enabled. 152 | 153 | A pcapng stream will be generated of packets, if any, matching the filter options. This stream will be buffered at the rate that the client is able to download it, and the stream will be closed at the end of the query. 154 | 155 | * Notes 156 | 157 | If the `kismet` log is not enabled, this endpoint will return an error. 158 | 159 | ## Dropping packets 160 | 161 | On very long-running Kismet processes, you may wish to purge old packets. These packets will be removed from the kismetdb log. 162 | 163 | * URL 164 | 165 | /logging/kismetdb/pcap/drop.cmd 166 | 167 | * API added 168 | 169 | `2018-12` 170 | 171 | * Methods 172 | 173 | `POST` 174 | 175 | * POST parameters 176 | 177 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 178 | 179 | | Key | Description | 180 | | --- | ----------- | 181 | | drop_before | A unix second timestamp value, packets older than `drop_before` will be deleted. | 182 | 183 | * Result 184 | 185 | `HTTP 200` on success 186 | 187 | HTTP error on failure 188 | 189 | -------------------------------------------------------------------------------- /devel/rest/095-phydot11.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Phy80211 Wi-Fi" 3 | permalink: /docs/devel/webui_rest/phy80211/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "The 802.11 Wi-Fi subsystem defines a set of Wi-Fi specific APIs for accessing information about APs, related devices, and more." 7 | --- 8 | The 802.11 Wi-Fi phy defines extra endpoints for manipulating Wi-Fi devices seen by Kismet, and for extracting packets of special types. 9 | 10 | ## WPA Handshakes 11 | The WPA handshake is vital for extracting the WPA key of an encrypted WPA or WPA2 session. Kismet will retain the handshake packets from an access point, and can provide them as a PCAP file. 12 | 13 | * URL 14 | 15 | /phy/phy80211/by-key/*[DEVICEKEY]*/pcap/handshake.pcap 16 | 17 | * API modified: 18 | 19 | `2020-10` 20 | 21 | * Methods 22 | 23 | `GET` 24 | 25 | * Role 26 | 27 | `readonly` 28 | 29 | * GET parameters 30 | 31 | | Key | Description | 32 | | --- | ---------- | 33 | | *[DEVICEKEY]* | Kismet device key of target device | 34 | 35 | * Roles 36 | 37 | `logon`, `readonly` 38 | 39 | * Result 40 | 41 | On success: PCAP file of WPA handshake packets associated with the device, as well as a beacon packet. 42 | 43 | On error: HTTP error 44 | 45 | ## WPA PMKID 46 | 47 | The WPA PMKID component of the handshake can be used to perform offline attacks against the WPA key using Aircrack or Hashcat. Kismet will retain a packet with the RSN PMKID value, and can provide it as a PCAP file. 48 | 49 | * URL 50 | 51 | /phy/phy80211/by-key/*[DEVICEKEY]*/pcap/handshake-pmkid.pcap 52 | 53 | * API added: 54 | 55 | `2019-05` 56 | 57 | * API modified: 58 | 59 | `2020-10` 60 | 61 | * Methods 62 | 63 | `GET` 64 | 65 | * Role 66 | 67 | `readonly` 68 | 69 | * GET parameters 70 | 71 | | Key | Description | 72 | | --- | ----------- | 73 | | *[DEVICEKY]* | Kismet device key of target device | 74 | 75 | * Roles 76 | 77 | `logon`, `readonly` 78 | 79 | * Result 80 | 81 | On success: PCAP file of RSN PMKID packet, and a beacon packet. 82 | 83 | On error: HTTP error 84 | 85 | ## Wi-Fi per-device pcap stream 86 | 87 | Kismet can provide a streaming pcap-ng log of all packets, from all interfaces, associated with a given Wi-Fi BSSID. Packets are streamed _starting when this endpoint is opened_, for past packtes, use the [KismetDB log API](/docs/devel/webui_rest/kismetdb/). 88 | 89 | * URL 90 | 91 | /phy/phy80211/pcap/by-bssid/*[BSSID]*/packets.pcapng 92 | 93 | * Methods 94 | 95 | `GET` 96 | 97 | * Role 98 | 99 | `readonly` 100 | 101 | * URL parameters 102 | 103 | | Key | Description | 104 | | --- | ---- | 105 | | *[BSSID]* | BSSID retrieve packets from | 106 | 107 | * Roles 108 | 109 | `logon`, `readonly` 110 | 111 | * Results 112 | 113 | A pcap-ng stream of packets which will stream indefinitely as packets are received. 114 | 115 | * Notes 116 | 117 | See the [packet capture API](/docs/devel/webui-rest/packet_capture/) for more information about pcap-ng streams 118 | 119 | ## Wi-Fi clients 120 | 121 | Kismet tracks client association with access points. This information is available as a list of the device keys in the access point device record, but it is also available through the clients API which will return the complete device record of the associated client. 122 | 123 | * URL 124 | 125 | /phy/phy80211/clients-of/*[DEVICEKEY]*/clients.json 126 | 127 | * Methods 128 | 129 | `GET` `POST` 130 | 131 | * Role 132 | 133 | `readonly` 134 | 135 | * URL parameters 136 | 137 | | Key | Description | 138 | | ---- | ---- | 139 | | *[DEVICEKEY]* | Device to fetch clients of. This should be an access point device; providing a non-access-point device will return an empty set. | 140 | 141 | * POST parameters 142 | 143 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 144 | 145 | | Key | Description | 146 | | --- | ----------- | 147 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 148 | 149 | * Roles 150 | 151 | `logon`, `readonly` 152 | 153 | * Results 154 | 155 | An array of device records of associated clients. 156 | 157 | ## Access points only view 158 | 159 | The 802.11 subsystem uses [device views](/docs/devel/webui_rest/device_views/) to provide a list of Wi-Fi access points. 160 | 161 | * URL 162 | 163 | /devices/views/phydot11_accesspoints/... 164 | 165 | /devices/views/phydot11_accesspoints/devices.json 166 | 167 | /devices/views/phydot11_accesspoints/last-time/*[TIMESTAMP]*/devices.json 168 | 169 | * Notes 170 | 171 | See the [views api](/docs/devel/webui_rest/device_views/) for more information 172 | 173 | ## Wi-Fi related devices 174 | 175 | Kismet can provide a list of related devices. Devices are related in 802.11 when they appear to be on the same physical network, or make up multiple BSSIDs in a roaming SSID. This can be seen when multiple APs share the same SSID, common clients, and appear as clients of each other. 176 | 177 | * URL 178 | 179 | /phy/phy80211/related-to/*[DEVICEKEY]*/devices.json 180 | 181 | * Methods 182 | 183 | `GET` `POST` 184 | 185 | * Role 186 | 187 | `readonly` 188 | 189 | * API added 190 | 191 | `2019-03` 192 | 193 | * URL parameters 194 | 195 | | Key | Description | 196 | | --- | --- | 197 | | *[DEVICEKEY]* | Device to fetch relationships for. This device should be an access point. Providing a non-access-point device will return an empty set. | 198 | 199 | * POST parameters 200 | 201 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 202 | 203 | | Key | Description | 204 | | --- | ----------- | 205 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 206 | 207 | * Roles 208 | 209 | `logon`, `readonly` 210 | 211 | * Results 212 | 213 | An array of device records of related devices. 214 | 215 | -------------------------------------------------------------------------------- /devel/rest/101-phydot11_ssidscan.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Phy802.11 SSID Scan module" 3 | permalink: /docs/devel/webui_rest/phy80211_ssidscan/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Still under development, the ssidscan module will allow for targetting devices by SSID and automatically searching for behavior." 7 | --- 8 | 9 | ## Under development 10 | 11 | SSID scan API is still incomplete and is under development 12 | 13 | ## SSIDScan status 14 | 15 | Current configuration and status of the ssidscan module, including the target SSIDs and assigned datasources. 16 | 17 | * API added 18 | 19 | `2019-04` 20 | 21 | * URL 22 | 23 | /phy/phy80211/ssidscan/status.json 24 | 25 | * Methods 26 | 27 | `POST` `GET` 28 | 29 | * Role 30 | 31 | `readonly` 32 | 33 | * POST parameters 34 | 35 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 36 | 37 | | Key | Description | 38 | | --- | ----------- | 39 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 40 | 41 | * Results 42 | 43 | `HTTP 200` on success 44 | 45 | HTTP error on failure 46 | 47 | ## SSIDScan configuration 48 | 49 | Push new configuration options to the ssidscan module, overriding any configuration present. 50 | 51 | * URL 52 | 53 | /phy/phy80211/ssidscan/config.cmd 54 | 55 | * API added 56 | 57 | `2019-04` 58 | 59 | * Methods 60 | 61 | `POST` 62 | 63 | * Role 64 | 65 | `admin` 66 | 67 | * POST parameters 68 | 69 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 70 | 71 | | Key | Description | 72 | | --- | ----------- | 73 | | ssidscan_enabled | Optional, boolean, enable or disable the ssidscan module | 74 | | ignore_after_handshake | Optional, boolean, ignore a target device once a WPA handshake has been captured | 75 | | max_capture_seconds | Optional, unsigned integer, maximum seconds to capture before returning to hop | 76 | | min_scan_seconds | Optional, unsigned integer, minumum seconds to scan before entering capture mode | 77 | | restrict_log_filters | Optional, restrict the kismetdb log to log only devices and packets meeting ssidscan targets. This will set filters but not remove existing logs. | 78 | | locking_datasources | Optional, vector of UUID strings of datasources assigned to the 'locking' pool to capture target devices | 79 | | hopping_datasources | Optional, vector of UUID strings of datasources assigned to the 'hopping' pool to scan for target devices | 80 | 81 | * Results 82 | 83 | `HTTP 200` on success 84 | 85 | HTTP error on failure 86 | 87 | -------------------------------------------------------------------------------- /devel/rest/102-phydot11_scansource.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Phy802.11 Scanning-mode Sources" 3 | permalink: /docs/devel/webui_rest/phy80211_scansource/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "A simple API for non-packet-capture 802.11 devices to report scanning results to Kismet" 7 | --- 8 | 9 | ## Scanning mode 10 | 11 | Properly capturing packets in Wi-Fi requires monitor mode and either a local Wi-Fi device or a high bandwidth connection. Scanning mode allows devices without special drivers to report networks to Kismet, but with some severe limitations: 12 | 13 | * Clients will not be visible. 14 | * The scanning mode device may transmit probe requests while scanning. 15 | * Enhanced information from the beacon such as max speed, etc, will often not be available. 16 | * Actual packet data will not be available. 17 | 18 | Scanning mode is really only appropriate for specific configurations, such as: 19 | 20 | * Mobile devices like Android or IOS reporting scan results to a central Kismet server 21 | * Embedded devices such as the ESP8266 or ESP32 22 | 23 | ## Scanning mode datasources 24 | 25 | Scanning mode datasources are created dynamically by Kismet when reports are submitted; there is no need to define a specific scanning mode datasource prior to sending a report. 26 | 27 | A scanning mode report must include: 28 | 29 | 1. A datasource UUID. This ID must be unique within Kismet, and consistent between all reports from this scanning source. Scanning software should cache this UUID for consistency. 30 | 31 | 2. A human-readable name. This will be assigned as the name of the datasource, and will be updated if it changes. Scanning software should cache this name for consistency. 32 | 33 | ## Cache/burst mode reporting 34 | 35 | Scanning mode assumes that the device doing scanning is not able to maintain a constant connection to the Kismet server. 36 | 37 | Reports can be cached and send in groups using the report endpoint; each report can contain a timestamp, GPS location, and signal information, and multiple reports over time can be sent for a single AP. 38 | 39 | ## Scanning mode report 40 | 41 | A scanning mode report consists of a [command dictionary](/docs/devel/webui_rest/commands/) holding an array of reports. Virtual datasources for each new report are automatically created. 42 | 43 | * API added 44 | 45 | `2020-06` 46 | 47 | * URL 48 | 49 | /phy/phy80211/scan/scan_report.cmd 50 | 51 | * Methods 52 | 53 | `POST` 54 | 55 | * Role 56 | 57 | `scanreport` 58 | 59 | * POST parameters 60 | 61 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 62 | 63 | | Key | Description | 64 | | --- | ----------- | 65 | | reports | Array containing multiple report objects | 66 | | source_name | A unique, consistent source name for the virtual datasource reporting this scan. | 67 | | source_uuid | A unique, consistent source UUID for the virtual datasource reporting this scan. | 68 | 69 | A report object should contain: 70 | 71 | | Key | Description | 72 | | --- | ----------- | 73 | | timestamp | (Optional) Unix timestamp at second precision. If no timestamp is provided, the time of this message is used. Due to general lack of precision of scanning mode, timestamp is second only. | 74 | | ssid | (Optional) SSID | 75 | | bssid | BSSID | 76 | | capabilities | (Optional) An Android or Wigle style string of encryption options, such as `[WPS]`, `[WPA-PSK-TKIP+CCMP]`, `[WEP]`, and so on. | 77 | | channel | (Optional) Quoted string channel, such as `"6"`, `"42HT40P"` | 78 | | freqkhz | (Optional) Frequency of AP, in KHz | 79 | | signal | Signal, in dBm | 80 | | lat | (Optional) GPS latitude | 81 | | lon | (Optional) GPS longitude | 82 | | alt | (Optional) GPS altitude | 83 | | speed | (Optional) GPS speed | 84 | 85 | * Results 86 | 87 | `HTTP 200` on success 88 | 89 | HTTP error on failure 90 | 91 | -------------------------------------------------------------------------------- /devel/rest/103-phydot11_ssidtracker.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "SSID views" 3 | permalink: /docs/devel/webui_rest/phy80211_ssid_tracker/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "A dedicated SSID aggregator API" 7 | --- 8 | 9 | ## SSID tracker 10 | 11 | The SSID tracker is a phy80211 specific mechanism for mapping SSID broadcast, probe, and response. 12 | 13 | A unique identifier is generated from the SSID content, length, and encryption options. 14 | 15 | Each SSID is mapped to a list of device keys organized by probe, response, and advertisement. 16 | 17 | ### SSID-based summarization and display 18 | 19 | Mirroring the [base summarization & display endpoint](/docs/devel/webui_rest/devices/#old-summarization--display) API, the SSID summarization endpoint is the primary interface for clients to access the SSID list and for scripts to retrieve lists of SSIDs. 20 | 21 | The SSID summarization is best utilized when applying a view window via the `start` and `length` variables. 22 | 23 | * URL 24 | 25 | /phy/phy80211/ssids/views/ssids.json 26 | 27 | * API added 28 | 29 | `2020-04` 30 | 31 | * Methods 32 | 33 | `POST` 34 | 35 | * Role 36 | 37 | `readonly` 38 | 39 | * POST parameters 40 | 41 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 42 | 43 | | Key | Description | 44 | | ------- | ----------------------------------------------------- | 45 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 46 | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | 47 | | colmap | Optional, inserted by the Kismet Datatable UI for mapping column information for proper ordering and sorting. | 48 | | 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. | 49 | 50 | Additionally, when in datatables mode, the following HTTP POST variables are used: 51 | 52 | | Key | Description | 53 | | --- | ---- | 54 | | start | Data view window start position | 55 | | length | Datatable window end | 56 | | draw | Datatable draw value | 57 | | search[value] | Search term, applied to all fields in the summary vector | 58 | | order\[0\]\[column\] | Display column number for sorting, indexed with colmap data | 59 | | order\[0\]\[dir\] | Sort order direction from jquery-datatables | 60 | 61 | * Results 62 | 63 | Summarized array of SSIDs 64 | 65 | ### SSID details 66 | 67 | Similar to the device details endpoint, a SSID details endpoint provides all the information about a tracked SSID entity. 68 | 69 | * URL 70 | 71 | /phy/phy80211/ssids/by-hash/*[HASH]*/ssid.json 72 | 73 | * API added 74 | 75 | `2020-08` 76 | 77 | * Methods 78 | 79 | `GET`, `POST` 80 | 81 | * Role 82 | 83 | `readonly` 84 | 85 | * URL parameters 86 | 87 | | Key | Description | 88 | | ------ | ---------------------------------------- | 89 | | *[HASH]* | Hash ID of the target SSID record | 90 | 91 | * POST parameters 92 | 93 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 94 | 95 | | Key | Description | 96 | | ------- | ----------------------------------------------------- | 97 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 98 | 99 | * Results 100 | 101 | SSID record 102 | 103 | -------------------------------------------------------------------------------- /devel/rest/105-phyuav.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "UAV / Drones" 3 | permalink: /docs/devel/webui_rest/phyuav/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Kismet can track additional information about UAV/Drone/Quadcopter devices based on manufacturer, SSID, and packet contents." 7 | --- 8 | The UAV/Drone phy defines extra endpoints for matching UAVs based on manufacturer and SSID. 9 | 10 | ## UAV manufacturers 11 | 12 | * URL 13 | 14 | /phy/phyuav/manuf_matchers.json 15 | 16 | /phy/phyuav/manuf_matchers.ekjson 17 | 18 | /phy/phyuav/manuf_matchers.itjson 19 | 20 | * Methods 21 | 22 | `GET` `POST` 23 | 24 | * Role 25 | 26 | `readonly` 27 | 28 | * POST parameters 29 | 30 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 31 | 32 | | Key | Description | 33 | | --- | ----------- | 34 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 35 | 36 | * Result 37 | 38 | Array of manufacturer match records 39 | 40 | -------------------------------------------------------------------------------- /devel/rest/110-phybluetooth_bluetoothscan.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "PhyBluetooth Scanning-mode Sources" 3 | permalink: /docs/devel/webui_rest/phybluetooth_scansource/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "A simple API for non-packet-capture bluetooth scanning results" 7 | --- 8 | 9 | ## Scanning mode datasources 10 | 11 | Scanning mode datasources are created dynamically by Kismet when reports are submitted; there is no need to define a specific scanning mode datasource prior to sending a report. 12 | 13 | A scanning mode report must include: 14 | 15 | 1. A datasource UUID. This ID must be unique within Kismet, and consistent between all reports from this scanning source. Scanning software should cache this UUID for consistency. 16 | 17 | 2. A human-readable name. This will be assigned as the name of the datasource, and will be updated if it changes. Scanning software should cache this name for consistency. 18 | 19 | ## Cache/burst mode reporting 20 | 21 | Scanning mode assumes that the device doing scanning is not able to maintain a constant connection to the Kismet server. 22 | 23 | Reports can be cached and send in groups using the report endpoint; each report can contain a timestamp, GPS location, and signal information, and multiple reports over time can be sent for a single AP. 24 | 25 | ## Scanning mode report 26 | 27 | A scanning mode report consists of a [command dictionary](/docs/devel/webui_rest/commands/) holding an array of reports. Virtual datasources for each new report are automatically created. 28 | 29 | * URL 30 | 31 | /phy/phybluetooth/scan/scan_report.cmd 32 | 33 | * API added 34 | 35 | `2020-07` 36 | 37 | * Methods 38 | 39 | `POST` 40 | 41 | * Role 42 | 43 | `scanreport` 44 | 45 | * POST parameters 46 | 47 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 48 | 49 | | Key | Description | 50 | | --- | ----------- | 51 | | reports | Array containing multiple report objects | 52 | | source_name | A unique, consistent source name for the virtual datasource reporting this scan. | 53 | | source_uuid | A unique, consistent source UUID for the virtual datasource reporting this scan. | 54 | 55 | A report object should contain: 56 | 57 | | Key | Description | 58 | | --- | ----------- | 59 | | timestamp | (Optional) Unix timestamp at second precision. If no timestamp is provided, the time of this message is used. Due to general lack of precision of scanning mode, timestamp is second only. | 60 | | btaddr | Bluetooth MAC address | 61 | | name | (Optional) Advertised device name | 62 | | devicetype | (Optional) Device type, if known | 63 | | txpowerlevel | (Option) Device advertised powerlevel (Integer) | 64 | | pathloss | (Optional) Path loss (Integer) | 65 | | signal | (Optional) Signal, in dBm (Integer) | 66 | | scan_data | (Optional) Binary scan data, as hex string | 67 | | service_data | (Optional) Dictionary of service UUID to service scan data as hex strings | 68 | | lat | (Optional) GPS latitude (Float) | 69 | | lon | (Optional) GPS longitude (Float) | 70 | | alt | (Optional) GPS altitude (Float) | 71 | | speed | (Optional) GPS speed (Float) | 72 | 73 | * Results 74 | 75 | `HTTP 200` on success 76 | 77 | HTTP error on failure 78 | 79 | -------------------------------------------------------------------------------- /devel/rest/115-phyadsb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "ADSB" 3 | permalink: /docs/devel/webui_rest/phyadsb/ 4 | toc: true 5 | docgroup: "devel-rest" 6 | excerpt: "Kismet can track aircraft using the ADSB transponder protocol using additional hardware" 7 | --- 8 | The ADSB PHY defines a websocket endpoint for obtaining a live stream of ADSB data in the binary BEAST format expected by some tools. 9 | 10 | ## ADSB BEAST websocket 11 | 12 | * URL 13 | 14 | /phy/RTLADSB/beast.ws 15 | 16 | * API Added 17 | 18 | `2020-11` 19 | 20 | * Methods 21 | 22 | `WEBSOCKET` (HTTP Upgrade + Websocket handshake) 23 | 24 | * Role 25 | 26 | `readonly`, `ADSB` 27 | 28 | * Result 29 | 30 | Streaming websocket output of ADSB data in BEAST format. 31 | 32 | * Notes 33 | 34 | This can be transformed into a TCP socket for external tools which expect that via the `websocat` tool, for example: 35 | 36 | ```bash 37 | $ websocat ws://user:password@kismet-server-ip/phy/RTLADSB/beast.ws | nc -l 12345 38 | ``` 39 | 40 | ## ADSB raw hex websocket 41 | 42 | * URL 43 | 44 | /phy/RTLADSB/raw.ws 45 | 46 | * API Added 47 | 48 | `2020-11` 49 | 50 | * Methods 51 | 52 | `WEBSOCKET` (HTTP Upgrade + Websocket handshake) 53 | 54 | * Role 55 | 56 | `readonly`, `ADSB` 57 | 58 | * Result 59 | 60 | Streaming websocket output of ADSB data in hex format which matches the output format of `dump1090 --raw` 61 | 62 | * Notes 63 | 64 | This can be easily dumped to tools which process hex ADSB streams with the `websocat` tool, for example: 65 | 66 | ```bash 67 | $ websocat ws://user:password@kismet-server-ip/phy/RTLADSB/raw.ws | some_tool... 68 | ``` 69 | 70 | ## ADSB raw hex websocket per-source 71 | 72 | * URL 73 | 74 | /datasource/by-uuid/*[UUID]*/adsb_raw.ws 75 | 76 | * API Added 77 | 78 | `2021-01` 79 | 80 | * Methods 81 | 82 | `WEBSOCKET` (HTTP Upgrade + Websocket handshake) 83 | 84 | * Role 85 | 86 | `readonly`, `ADSB` 87 | 88 | * Result 89 | 90 | Streaming websocket output of ADSB data in hex format which matches the output format of `dump1090 --raw`. The feed is restricted to the specified source. 91 | 92 | * Notes 93 | 94 | This can be easily dumped to tools which process hex ADSB streams with the `websocat` tool, for example: 95 | 96 | ```bash 97 | $ websocat ws://user:password@kismet-server-ip/phy/RTLADSB/raw.ws | some_tool... 98 | ``` 99 | -------------------------------------------------------------------------------- /devel/rest/_base.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "xyz" 3 | permalink: /docs/devel/webui_rest/xyz/ 4 | toc: true 5 | --- 6 | 7 | ## System status 8 | * URL \\ 9 | 10 | * Methods \\ 11 | `GET` `POST` 12 | 13 | * POST parameters \\ 14 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 15 | 16 | | Key | Description | 17 | | --- | ----------- | 18 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 19 | 20 | * Result \\ 21 | Dictionary of Kismet system-level status, including update, battery, memory, and thermal data, optionally simplified. 22 | 23 | -------------------------------------------------------------------------------- /devel/rest/_links.md: -------------------------------------------------------------------------------- 1 | 2 | * POST parameters \\ 3 | A [command dictionary](/docs/devel/webui_rest/commands/) containing: 4 | | Key | Description | 5 | | --- | ----------- | 6 | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | 7 | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | 8 | | timestamp | Optional, relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | 9 | -------------------------------------------------------------------------------- /howto/openwrt.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Building Kismet for OpenWRT" 3 | permalink: /docs/howto/openwrt/ 4 | toc: true 5 | --- 6 | 7 | # Building Kismet for OpenWRT 8 | 9 | ## Kismet on OpenWRT 10 | 11 | Thanks to the hard work of [Foxtrot](https://twitter.com/justfoxtrot) at Hak5, there are now official Kismet Makefiles for OpenWRT, and the packages are already included in the repositories for the Wi-Fi Pineapples! 12 | 13 | For building in generic OpenWRT instances, read on... 14 | 15 | ## Kismet needs a lot of resources 16 | 17 | Kismet tracks a *lot* of information about different networks and devices, which takes a lot of RAM. Most OpenWRT targets have very limited resources for flash and RAM and are not best suited for running Kismet. Usually, these devices are best suited for running the Kismet remote capture code, feeding packets to a full Kismet server on 'real' hardware. 18 | 19 | It is possible to run a full Kismet server, and the package scripts provided attempt to disable the most memory-consuming aspects of Kismet while retaining functionality, however most systems running OpenWRT will run into limitations. 20 | 21 | ## Get the OpenWRT code 22 | 23 | Check out a recent version of the OpenWRT/LEDE codebase: 24 | 25 | ```bash 26 | $ git clone https://github.com/openwrt/openwrt.git 27 | ``` 28 | 29 | ## Get the Kismet packaging code 30 | 31 | ```bash 32 | $ git clone https://github.com/kismetwireless/kismet-packages.git 33 | ``` 34 | 35 | ## Install the OpenWRT feeds 36 | 37 | We need to tell OpenWRT to pull the feeds into the build system. The feeds system includes many packages Kismet needs to compile. Change to the OpenWRT directory you checked out, and run: 38 | 39 | ```bash 40 | $ cd openwrt 41 | $ ./scripts/feeds update -a 42 | $ ./scripts/feeds install -a 43 | ``` 44 | 45 | This will download all the third-party package definitions. They'll be needed by the Kismet packages. 46 | 47 | ## Copy or link the Kismet packages 48 | 49 | Copy, or symlink, the Kismet package definitions. From the `openwrt` directory you should already be in: 50 | 51 | ```bash 52 | $ cp -R ../kismet-packages/openwrt/kismet-openwrt packages/ 53 | ``` 54 | 55 | This assumes you checked out the kismet-packages repository in the same directory that you checked out OpenWRT; if you used a different directory, of course copy from there instead. 56 | 57 | ## Configure OpenWRT 58 | 59 | You will need to configure your basic options for OpenWRT, such as the processor and board. This needs to match the processor of the target system you are building packages for. 60 | 61 | ```bash 62 | $ make menuconfig 63 | ``` 64 | 65 | ## Enable Kismet 66 | 67 | Now we need to enable the Kismet package. In the OpenWRT config tool still: 68 | 69 | 1. Navigate to `Network` 70 | 2. Scroll to `kismet`. 71 | 3. Inside the `kismet` option will be many possible sub-packages. Enable the packages you need *as modules*. 72 | 73 | ## Kismet packages 74 | 75 | Kismet is split into multiple packages to minimize the storage required; you can pick and choose what sub-packages you need: 76 | 77 | * `kismet` 78 | 79 | The base Kismet server and WebUI. This is required for running a full Kismet instance, and is the most resource intensive. Many OpenWRT systems are not suitable for running a Kismet server, and are better suited running the remote capture tools. 80 | 81 | To capture packets, you will need one or more of the `kismet-capture-xyz` packages. 82 | 83 | * `kismet-manuf-database` 84 | 85 | The compressed Kismet manufacturer database allows Kismet to resolve MAC addresses to manufacturers. This package is only of use when running a full Kismet server. 86 | 87 | * `kismet-icao-database` 88 | 89 | The compressed Kismet ICAO database is a very large dataset of ICAO aircraft registration. This package is only of use when running a full Kismet server, and using the ADSB SDR capture tool. 90 | 91 | * `kismet-capture-linux-wifi` 92 | 93 | The Linux Wi-Fi capture driver for Kismet; this provides both *local* capture for a full Kismet server install, and *remote* capture for using an OpenWRT device as a capture node. 94 | 95 | This is required to capture Wi-Fi packets on OpenWRT. 96 | 97 | * `kismet-capture-linux-bluetooth` 98 | 99 | The Linux HCI Bluetooth capture driver for Kismet; this provides both *local* capture for a full Kismet server install, and *remote* capture for using an OpenWRT device as a capture node. 100 | 101 | This is required to detect Bluetooth networks, and requires a HCI Bluetooth adapter. 102 | 103 | * `kismet-capture-sdr-rtladsb` 104 | 105 | The ADSB capture driver for Kismet; this provides both *local* capture for a full Kismet server install, and *remote* capture for using an OpenWRT device as a capture node. 106 | 107 | This is required to detect aircraft via ADSB, and requires a RTLSDR radio. This also requires python3 support, and can be quite resource intensive. 108 | 109 | * `kismet-capture-sdr-rtlamr` 110 | 111 | The AMR capture driver for Kismet; this provides both *local* capture for a full Kismet server install, and *remote* capture for using an OpenWRT device as a capture node. 112 | 113 | This is required to detect utility meters over AMR, and requires a RTLSDR radio. This also requires python3 support, and can be quite resource intensive. 114 | 115 | * `kismet-capture-sdr-rtl433` 116 | 117 | The 433Mhz switch, sensor, thermometer, and related capture driver for Kismet; this provides both *local* capture for a full Kismet server install, and *remote* capture for using an OpenWRT device as a capture node. 118 | 119 | This is required to detect multiple types of devices which can be seen with the rtl433 tool, including weather stations, TPMS sensors, thermometers, switches, and similar, and requires a RTLSDR radio. This also requires python3 support, and can be quite resource intensive. 120 | 121 | * `kismet-tools` 122 | 123 | Assorted Kismet host tools for log manipulation and conversion; these are typically better run on a full system with more resources. 124 | 125 | * Assorted Python3 libraries 126 | 127 | Some Kismet capture drivers use Python3 modules not currently present in normal OpenWRT feeds; package definitions for these modules are included in the `kismet-openwrt` packaging directory and are automatically enabled when one of the Kismet python3-based capture tools is selected. 128 | 129 | ## Compile OpenWRT 130 | 131 | Now we need to start the build process: It will take a while. 132 | 133 | ``` 134 | $ make 135 | ``` 136 | 137 | Depending on how many processors your system has, you can speed this up with 138 | 139 | ``` 140 | $ make -j$(nproc) 141 | ``` 142 | 143 | or similar. 144 | 145 | ## Copy the packages! 146 | 147 | If everything went well, you now have a bunch of packages to copy (or a firmware image to flash). They can be found in `build_dir/target_[your target processor]`. Remember you may need to copy many sub-packages to your device as well! 148 | 149 | 150 | -------------------------------------------------------------------------------- /howto/remote-capture-build.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "OpenWRT remote capture" 3 | permalink: /docs/howto/openwrt_remote/ 4 | toc: true 5 | --- 6 | 7 | # Building Kismet-Git remote capture for OpenWrt 8 | 9 | A number of people have asked how to get Kismet remote capture running on OpenWrt - until the final release of the new Kismet is done, or if you'd like to play with the git version going forward, here's a quick tutorial. 10 | 11 | *Please remember* git versions of Kismet are unstable and under development - not everything may work, or things may change rapidly. Generally the git versions are usable but every so often you'll get a bad version. 12 | 13 | These instruction are meant to be a quick guide to getting the Kismet specifics compiled, so I recommend checking out some OpenWrt build guides if you're completely new to the whole process. 14 | 15 | ## Step one: Install build-essentials or your distros equivalent 16 | 17 | If you don't have them already, you'll need `build-essentials` and `git`. 18 | 19 | ## Get the Kismet code 20 | 21 | You'll want the Kismet source code to get the openwrt package definition. 22 | 23 | ``` 24 | $ git clone https://www.kismetwireless.net/kismet.git 25 | ``` 26 | 27 | This will take a little while to download, and due to how Git handles https servers, may look like it's hung - just give it time. 28 | 29 | ## Get the OpenWrt code 30 | 31 | ``` 32 | $ git clone https://git.openwrt.org/openwrt/openwrt.git 33 | ``` 34 | 35 | ## Do the basic OpenWrt Config 36 | 37 | You will need to select the basic options for OpenWrt and enable the external feed for additional libraries Kismet needs. When running `make menuconfig` you may see warnings about needing additional packages - install any that OpenWrt says you are missing. 38 | 39 | ```bash 40 | # Go into the directory you just cloned 41 | $ cd openwrt 42 | 43 | # Start the configuration tool 44 | $ make menuconfig 45 | ``` 46 | 47 | Inside the OpenWRT configuration you will want to: 48 | 49 | 1. Confirm that the correct platform is selected. For example: 50 | `Target System (Atheros AR7xxx/AR9xxx) ` 51 | and 52 | ` Subtarget (Generic)` 53 | Because we are only trying to build packages and not a complete system, we don't need to configure the image formats; default is fine. 54 | 2. Navigate to `Image Configuration`. 55 | 3. Navigate to `Separate Feed Repositories`. 56 | 4. Select `Enable feed packages`. 57 | 5. Exit the config tool. When prompted to save, do so. 58 | 59 | ## Install the feeds 60 | 61 | We need to tell OpenWrt to pull the feeds into the build system. Still in the openwrt directory you checked out, run: 62 | 63 | ```bash 64 | $ ./scripts/feeds update -a 65 | $ ./scripts/feeds install -a 66 | ``` 67 | 68 | This will download all the third-party package definitions. 69 | 70 | ## Copy the Kismet package definition 71 | 72 | We want to copy the Kismet package over, because we'll potentially be making some modifications. 73 | 74 | ``` 75 | $ cp -R kismet/packaging/openwrt/kismet-remote-2018 openwrt/package/network 76 | ``` 77 | 78 | Where, of course, you want to copy from your checked-out Kismet code to the checked-out OpenWrt code; your directories might be different. 79 | 80 | ## Install libprotoc-c 81 | 82 | In a perfect world the libprotoc-c package in OpenWRT would install the proper host binary for protoc-c, but it does not. Fortunately, there is only one version of libproto-c (the C-only version), so the package for your host distribution should be sufficient. 83 | 84 | ``` 85 | $ sudo apt-install protobuf-c-compiler 86 | ``` 87 | 88 | will suffice on Ubuntu-style distributions; your distribution may vary. Note: This is for the *protobuf-c* version, *not* the normal protobuf (which is C++, and which has a working openwrt package with proper host tools). 89 | 90 | ## Enable Kismet 91 | 92 | Now we need to enable the Kismet package. Still in your OpenWrt directory: 93 | 94 | 1. Enter OpenWrt configuration again: `make menuconfig`. 95 | 2. Navigate to 'Network'. 96 | 3. Scroll all the way down to 'kismet-remote', it will be several screens down. 97 | 4. Enable kismet-remote as a *module*. Hit 'm' to do so. 98 | 5. Exit, saving when prompted to do so. 99 | 100 | ## Compile OpenWrt 101 | 102 | Now we need to start the build process: It will take a while. 103 | 104 | ``` 105 | $ make 106 | ``` 107 | 108 | Depending on how many processors your system has, you can speed this up with 109 | 110 | ``` 111 | $ make -j4 112 | ``` 113 | 114 | or similar. 115 | 116 | If you still get an error regarding protoc-c not found, you may have to link you local version where the OpenWrt version is supposed to be, like: 117 | 118 | ``` 119 | ln -s /usr/bin/protoc-c staging_dir/target-_musl-1.1.16/host/bin/protoc-c 120 | ``` 121 | 122 | ## Copy the packages! 123 | 124 | If everything went well, you now have two packages to copy to your OpenWrt: 125 | ```bash 126 | $ cd bin/packages// 127 | $ scp packages/libprotobuf-c.ipk base/kismet-remote.ipk root@openwrt-machine:/tmp 128 | ``` 129 | ## Install Kismet on OpenWrt 130 | 131 | SSH into the OpenWrt and install the packages: 132 | 133 | ```bash 134 | $ ssh root@openwrt-machine 135 | ... 136 | # cd /tmp 137 | # opkg install *.ipk 138 | ``` 139 | 140 | ## Run Kismet! 141 | 142 | Fire up Kismet remote capture and see how it goes. While SSHed into the OpenWrt as root: 143 | ``` 144 | # kismet_cap_linux_wifi --connect [host]:[port] --source=wlan0 145 | ``` 146 | or alike. Use `--help` for more information. 147 | 148 | -------------------------------------------------------------------------------- /howto/win10.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismet on Win10 WSL" 3 | permalink: /docs/howto/win10/ 4 | toc: true 5 | --- 6 | 7 | # Compiling and Running Kismet on Windows 10 8 | 9 | With the introduction of the Windows Subsystem for Linux (WSL), it's now possible to run the Kismet server on a Win10 system. 10 | 11 | There is one major caveat: Kismet will not be able to capture packets from your local Wi-Fi interface. You *must* use a remote Kismet capture source - this could be a Linux system, or an embedded capture device like a Wi-Fi Pineapple Tetra or another simple OpenWRT or LEDE device. 12 | 13 | ## Why would I want to do this? 14 | 15 | The main advantage of running Kismet in the WSL is to leverage the full capabilities of your Win10 device, while capturing from a super-lightweight capture device like a Tetra, other OpenWRT, or even Raspberry Pi class device. 16 | 17 | ## Pre-Req 1: Windows 10 18 | 19 | The WSL only exists for Windows 10; this is not possible under Windows 8 or 9. 20 | 21 | ## Pre-Req 2: Activate and install the WSL 22 | 23 | You will need to activate the WSL system, and then install a Linux distribution, as per the instructions at: 24 | 25 | [https://docs.microsoft.com/en-us/windows/wsl/install-win10](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 26 | 27 | The choice of distribution to install is up to you; Ubuntu is the most logical choice as it is known to have compatibility with Kismet. 28 | 29 | Ubuntu 18.04 LTS, along with other versions (Kali, for example), is available directly from the Windows Store: 30 | [https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q](https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q) 31 | 32 | ## Install dependencies 33 | 34 | You'll need many of the dependencies Kismet needs to compile; you could install them all, but at a minimum you need to update the Ubuntu systems package lists and install: 35 | 36 | ```bash 37 | $ sudo apt update 38 | $ sudo apt install build-essential libmicrohttpd-dev git libpcap-dev libsqlite3-dev 39 | ``` 40 | 41 | ## Check out Kismet 42 | 43 | As you would on Linux: 44 | 45 | ``` 46 | $ git clone https://www.kismetwireless.net/git/kismet.git 47 | ``` 48 | 49 | ## Configure and compile 50 | 51 | ``` 52 | $ cd kismet 53 | $ ./configure 54 | $ make 55 | ``` 56 | 57 | ## Install 58 | 59 | Install - there's no reason to install as suidroot here since we will not be locally managing interfaces. 60 | 61 | ``` 62 | $ sudo make install 63 | ``` 64 | 65 | ## Configure for remote capture 66 | 67 | Check the Kismet main README file for more information on configuring remote capture; you can configure it to allow connections from remote sources, OR you can use a tool like `ssh` to tunnel a remote capture secure. 68 | 69 | ## Launch Kismet 70 | 71 | Run Kismet like you would on Linux: 72 | 73 | ``` 74 | $ kismet 75 | ``` 76 | 77 | or, without logging, 78 | 79 | ``` 80 | $ kismet -n 81 | ``` 82 | 83 | ## Visit the Kismet server via the browser 84 | 85 | Open your browser and go to `http://localhost:2501` to reach the Kismet server. 86 | 87 | The password to the server will be automatically generated the first time Kismet starts. You can find the password in the WSL filesystem under `~/.kismet/kismet_httpd.conf`. 88 | 89 | ## Fire up some remote captures 90 | 91 | Fire up some remote captures (consult the main Kismet README for more info) and point them at your new server, and watch the packets come in! 92 | 93 | 94 | 95 | -------------------------------------------------------------------------------- /readme/000-intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction" 3 | permalink: /docs/readme/intro/ 4 | excerpt: "A quick introduction to what Kismet is, isn't, and how it works" 5 | docgroup: "readme" 6 | --- 7 | 8 | ## Kismet 9 | 10 | Kismet is a monitoring tool for wireless - originally only supporting 802.11 Wi-Fi, with the right hardware Kismet can now capture Bluetooth advertisements, BTLE, nRF-based wireless mice and keyboards, weather stations, wireless thermometers, switches, smoke detectors, 802.15.4 / Zigbee, ADSB airplane transponders, AMR wireless power, water, and gas meters, and more. 11 | 12 | ## Passive monitoring 13 | 14 | Kismet operates almost entirely passively, with a few exceptions (such as Bluetooth scanning mode) noted in the documentation for those capture types. 15 | 16 | Kismet is *not* an attack tool (generally) - to test your Wi-Fi security check out tools like [Aircrack-NG](https://www.aircrack-ng.org) or the [Wi-Fi Pineapple](https://shop.hak5.org/). 17 | 18 | Kismet is largely focused on collecting, collating, and sorting wireless data. The logs generated by Kismet can be fed into other tools (the pcap, handshakes, and other data) like hashcat, aircrack, and more. 19 | 20 | ## Device-oriented display 21 | 22 | Kismet is different from [Wireshark](https://wireshark.org); Kismet primarily focuses on representing *devices* - access points, clients, bridged wired devices, sensors, Bluetooth entities, and so on, while Wireshark focuses on displaying a deep dive of specific packets and all the content. 23 | 24 | Kismet and Wireshark work best when used *together* - Kismet collects packets and logs them to standard formats (pcap and pcapng) or the kismetdb format which can be converted directly to pcap and pcapng, and collects location, changes over time, etc, while Wireshark can open the pcap logs and give extensive detailed information about specific packets. Each tool is designed for a different job, but operate together. 25 | 26 | ## Wireless vs Wired monitoring 27 | 28 | Wireless capture is often more difficult than wired capture, at several levels: 29 | 30 | * Different physical characteristics 31 | 32 | When connecting to a wired network and capturing packets, you will always capture all packets available on that connection (assuming you have sufficient processing power and storage speed to log them, of course). When capturing packets from a wireless network, things are very different; your receiver may not be in a position to even see the packets that the legitimate destination can receive fine, you may not be on the correct channel or part of the spectrum when the packets are sent, there may be localized interference, or you may be in the center of reflected signals that cancel each other out. 33 | 34 | * Drivers 35 | 36 | To capture raw packets from a Wi-Fi device, a mode called "monitor mode" or "rfmon" is required - this is a non-standard mode which turns off packet filtering in the Wi-Fi card itself and passes raw data up to the operating system. While most drivers in the Linux kernel support this, not all do. Mobile chipsets (such as those found in Android phones or Raspberry Pi devices) typically do not have the code in the device firmware *at all* and either cannot be used, or require special driver hacks to re-enable it. Other operating systems like Windows have nearly no monitor-mode capable public drivers, and MacOS can enter monitor mode for the internal Airport cards, but typically not on any other type of Wi-Fi. 37 | 38 | Other non-Wi-Fi protocols often have no radio support, or lack drivers. Sometimes this is solved with special hardware and drivers, sometimes it can be solved with software defined radios. 39 | 40 | * Many protocols 41 | 42 | Wi-Fi alone has at least 6 major revisions, each of which is largely invisible to hardware of the previous generation, combined with 3 major spectrum bands. Each revision increases speed (decreasing effective signal) and complexity of the signal (MIMO, sub-channels, etc) which make capturing data harder. 43 | 44 | That's just Wi-Fi - add in Bluetooth, Zigbee, arbitrary RF protocols, and the amount of hardware and software needed to capture what is flying around in the air explodes. 45 | 46 | -------------------------------------------------------------------------------- /readme/001-git_version.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Git and Beta" 3 | permalink: /docs/readme/git_and_beta/ 4 | excerpt: "Welcome to the new, MAJOR rewrite of Kismet! If you're using the old versions, you'll want to do some housekeeping..." 5 | docgroup: "readme" 6 | --- 7 | 8 | ## OLDER KISMET 9 | 10 | Kismet has undergone several major evolutions over time. Some distributions still package the old Kismet versions: If you're still using the text-based UI, you'll definitely want to upgrade; not only for the new features, but for significantly reduced RAM and significantly increased performance on modern systems and modern Wi-Fi deployments, which have orders of magnitude more devices on Wi-Fi to track! 11 | 12 | ## MAJOR KISMET UPDATE 13 | 14 | Welcome to the new, MAJOR rewrite of Kismet! This version changes almost everything, hopefully for the better, including: 15 | 16 | * Web-based UI allowing for much simpler presentation of data and compatibility with mobile devices 17 | 18 | * Standard JSON-based data export for easy scripting against Kismet instances 19 | 20 | * Support for wireless protocols beyond Wi-Fi, like basic Bluetooth scanning, thermometer, and weather station detection with the RTL-SDR hardware, and more on the way 21 | 22 | * New remote-capture code optimized for binary size and RAM, allowing extremely low-end embedded devices to be used for packet capture 23 | 24 | * New logging format which can encapsulate complex information about devices, system state, alerts, messages, and packets in a single file with simple tools for extracting standard formats 25 | 26 | * Pcap-NG multi-interface logs with complete original headers, readable by Wireshark and other tools 27 | 28 | Please remember that with this major release, there is still some work to be done and warts to be taken care of, but the codebase has been under development and in use for several years and has been performing well. 29 | 30 | Setting up the new Kismet is generally simpler than the older versions; keep reading for more information! 31 | 32 | At the *very least* you will need to uninstall any old versions of Kismet, and you will need to install the new config files with `make forceconfigs`. Read on for more info! 33 | 34 | -------------------------------------------------------------------------------- /readme/010-suid.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Installing Kismet: SUID vs Non-SUID" 3 | permalink: /docs/readme/suid/ 4 | excerpt: "Kismet can be installed and configured multiple ways; the most secure is to allow Kismet to be installed suidroot and executable by users in the kismet group only." 5 | docgroup: "readme" 6 | --- 7 | 8 | ## Installing Kismet - Suid vs Normal 9 | 10 | It is **strongly** recommended that Kismet never be run as root; instead use the Kismet suid-root installation method; when compiling from source it can be installed via: 11 | ``` 12 | $ ./configure 13 | $ make 14 | $ sudo make suidinstall 15 | ``` 16 | 17 | Nearly all packages of Kismet *should* support the suid-root install method as well. 18 | 19 | This will create a new group, `kismet`, and install capture tools which need root access as suid-root but only runnable by users in the `kismet` group. 20 | 21 | This will allow anyone in the Kismet group to change the configuration of wireless interfaces on the system, but will prevent Kismet from running as root. 22 | 23 | #### Why does Kismet need root? 24 | 25 | Controlling network interfaces on most systems requires root, or super-user access. 26 | 27 | While written with security strongly in mind, Kismet is a large and complex program, which handles possibly hostile data from the world. This makes it a very bad choice to run as root. 28 | 29 | To mitigate this, Kismet uses separate processes to control the network interfaces and capture packets. These capture programs are much smaller than Kismet itself, and do minimal (or no) processing on the contents of the packets they receive. 30 | 31 | -------------------------------------------------------------------------------- /readme/011-starting.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Starting Kismet" 3 | permalink: /docs/readme/starting_kismet/ 4 | excerpt: "Configuring and starting Kismet for the first time" 5 | docgroup: "readme" 6 | --- 7 | 8 | ## The Basics 9 | 10 | Kismet can be started normally from the command line, and shows a small text-based display of the recent output from the server. For the modern UI experience, you'll need to connect to the Kismet webserver. 11 | 12 | If you're on the same hardware as Kismet (such as a laptop), you will connect to `http://localhost:2501` to reach the Kismet server. 13 | 14 | If you're running Kismet on dedicated hardware (such as a Raspberry Pi, Hak5 Wi-Fi Pineapple, or other dedicated device), you'll need to connect to *the address of the device*. For a Raspberry Pi this is often `http://raspberyrpi.local:2501` by default, but you will need to check the configuration of your device. It will be the same address you connect to over `ssh` to launch Kismet. 15 | 16 | ## Launching Kismet 17 | 18 | Kismet can be run with no options and configured completely from the web interface: 19 | 20 | ```bash 21 | $ kismet 22 | ``` 23 | 24 | Or you can point it directly at a network interface and it will configure it during startup. Different operating systems, kernel versions, and distributions all name network interfaces differently; your Wi-Fi interface may be something like `wlan0`, `wlan1`, or `wlp0s1`. It may be named based on the MAC address, such as `wlx00aabbccddee`. On OSX, it is typically named something like `en1`. 25 | 26 | If you do not already know the name of your network interface, you can either use the Datasources panel in the WebUI to automatically discover it, or you can use `ifconfig`, `ip`, `iw dev`, and similar commands to find the available network interfaces and identify which one is your wireless interface you plan to use with Kismet. 27 | 28 | Once you have identified an interface, you can start Kismet with that source already defined, for example: 29 | 30 | ```bash 31 | $ kismet -c wlan0 32 | ``` 33 | 34 | *Remember, until you add a data source, Kismet will not be capturing any packets!* 35 | 36 | ## More than just Wi-Fi 37 | 38 | Kismet handles much more than just Wi-Fi, assuming you have the proper capture hardware. Be sure to check out the data sources category of the Kismet documentation! 39 | 40 | ## First-time setup 41 | 42 | *THE FIRST TIME YOU RUN KISMET*, you *MUST* go to the Kismet WebUI and set your login and password. 43 | 44 | This login will be saved in the config file: `~/.kismet/kismet_httpd.conf` which is in the *home directory of the user* starting Kismet when installed in suidroot mode. This is the preferred way to run Kismet. 45 | 46 | If you start Kismet as or via sudo (or via a system startup script where it runs as root), this will be in *roots* home directory: `/root/.kismet/kismet_httpd.conf` 47 | 48 | ## Automatically launching Kismet 49 | 50 | An example systemd script is in the `packaging/systemd/` directory of the Kismet source; if you are installing from source this can be copied to `/etc/systemd/system/kismet.service`, and packages should automatically include this file. 51 | 52 | When starting Kismet via systemd, you should install kismet as suidroot, and use `systemctl edit kismet.service` to set the following: 53 | 54 | ``` 55 | [Service] 56 | User=your-unprivileged-user 57 | Group=kismet 58 | ``` 59 | 60 | Also, when using systemd (or any other startup script system), you will need to be sure to configure Kismet to log to a valid location. By default, Kismet logs to the directory it is launched from, which is unlikely to be valid when starting from a boot script. 61 | 62 | Be sure to put a `log_prefix=...` in your [kismet_site.conf](https://www.kismetwireless.net/docs/readme/config_files/#configuration-override-files---kismet_siteconf); for example 63 | 64 | ``` 65 | log_prefix=/home/kismet/logs 66 | ``` 67 | 68 | If you encounter errors launching Kismet from a startup script, be sure to check either `journalctl -xe` or your syslogs for more information. 69 | 70 | -------------------------------------------------------------------------------- /readme/015-upgrading.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Upgrading" 3 | permalink: /docs/readme/upgrading/ 4 | excerpt: "If you're upgrading from the old Kismet legacy release, or following the new git code, you may need to do some special care and feeding of your setup when you upgrade." 5 | docgroup: "readme" 6 | --- 7 | 8 | ## Upgrading & Using Kismet Git-Master (or beta) 9 | 10 | The safest route is to remove any old Kismet version you have installed - by uninstalling the package if you installed it via your distribution, or by removing it manually if you installed it from source (specifically, be sure to remove the binaries `kismet_server`, `kismet_client`, and `kismet_capture`, by default found in `/usr/local/bin/` and the config file `kismet.conf`, by default in `/usr/local/etc/`. 11 | 12 | You can then configure, and install, the new Kismet per the quickstart guide above. 13 | 14 | While heavy development is underway, the config file may change; generally breaking changes will be mentioned on Twitter and in the git commit logs. 15 | 16 | Sometimes the changes cause problems with Git - such as when temporary files are replaced with permanent files, or when the Makefile removes files that are now needed. If there are problems compiling, the easiest first step is to remove the checkout of directory and clone a new copy (simply do a `rm -rf` of the copy you checked out, and `git clone` a new copy) 17 | -------------------------------------------------------------------------------- /readme/020-debugging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Debugging" 3 | permalink: /docs/readme/debugging/ 4 | excerpt: "As hard as we try, everything has bugs. If you're having trouble with Kismet, here's how to help with the debugging!" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Debugging Kismet 10 | 11 | Kismet (especially in beta) is in a state of rapid development - this means that bad things can creep into the code. Sorry about that! 12 | 13 | If you're interested in helping debug problems with Kismet, here's the most useful way to do so: 14 | 15 | 1. Compile Kismet from source (per the quick start guide above) 16 | 17 | 2. Install Kismet (typically via `sudo make suidinstall`) 18 | 19 | 3. Run Kismet, *FROM THE SOURCE DIRECTORY*, in `gdb`: 20 | 21 | ```bash 22 | $ gdb ./kismet 23 | ``` 24 | 25 | This loads a copy of Kismet with all the debugging info intact; the copy of Kismet which is installed system-wide usually has this info removed; the installed version is 1/10th the size, but also lacks a lot of useful information which we need for proper debugging. 26 | 27 | 4. Tell GDB to ignore the PIPE signal 28 | 29 | ``` 30 | (gdb) handle SIGPIPE nostop noprint pass 31 | ``` 32 | 33 | This tells GDB not to intercept the SIGPIPE signal (which can be generated, among other times, when a data source has a problem) 34 | 35 | 5. Configure GDB to log to a file 36 | 37 | ``` 38 | (gdb) set logging on 39 | ``` 40 | 41 | This saves all the output to `gdb.txt` 42 | 43 | 5. Run Kismet - *in debug mode* 44 | 45 | ``` 46 | (gdb) run --debug [any other options] 47 | ``` 48 | 49 | This turns off the internal error handlers in Kismet; they'd block gdb from seeing what happened. You can specify any other command line options after --debug; for instance: 50 | 51 | ```` 52 | (gdb) run --debug -n -c wlan1 53 | ```` 54 | 55 | 6. Wait for Kismet to crash 56 | 57 | 7. Collect a backtrace 58 | ``` 59 | (gdb) bt 60 | ``` 61 | 62 | This shows where Kismet crashed. 63 | 64 | 8. Collect thread info 65 | ``` 66 | (gdb) info threads 67 | ``` 68 | 69 | This shows what other threads were doing, which is often critical for debugging. 70 | 71 | 9. Collect per-thread backtraces 72 | ``` 73 | (gdb) thread apply all bt full 74 | ``` 75 | 76 | This generates a dump of all the thread states 77 | 78 | 10. Send us the gdb log and any info you have about when the crash occurred; dragorn@kismetwireless.net or swing by IRC or the Discord channel (info available about these on the website, https://www.kismetwireless.net) 79 | 80 | #### Advanced debugging 81 | 82 | If you're familiar with C++ development and want to help debug even further, Kismet can be compiled using the ASAN memory analyzer; to rebuild it with the analyser options: 83 | 84 | ``` 85 | $ make clean 86 | $ CC=clang CXX=clang++ ./configure --enable-asan 87 | ``` 88 | 89 | ASAN has a performance impact and uses significantly more RAM, but if you are able to recreate a memory error inside an ASAN instrumented Kismet, that will be very helpful. 90 | 91 | -------------------------------------------------------------------------------- /readme/025-config_files.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Config Files" 3 | permalink: /docs/readme/config_files/ 4 | excerpt: "Kismet has a large set of options which can be configured via configuration files - and sanely managed during upgrades with kismet_site.conf" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Configuring Kismet 10 | 11 | Kismet is primarily configured through a set of configuration text files. By default these are installed into `/usr/local/etc/` when compiling from source, and `/etc/kismet/` when installing from the Kismet packages. The config files are broken into several smaller files for readability: 12 | 13 | * `kismet.conf` 14 | The master config file which loads all other configuration files, and contains most of the system-wide options 15 | 16 | * `kismet_alerts.conf` 17 | Alert / WIDS configuration, which includes rules for alert matching, rate limits on alerts, and other IDS/problem detection options 18 | 19 | * `kismet_httpd.conf` 20 | Webserver configuration 21 | 22 | * `kismet_memory.conf` 23 | Memory consumption and system tuning options. Typically unneeded, but if you have a massive number of devices or an extremely resource-limited system, how Kismet uses memory can be tuned here. 24 | 25 | * `kismet_storage.conf` 26 | Kismet persistent storage configuration 27 | 28 | * `kismet_logging.conf` 29 | Log file configuration 30 | 31 | * `kismet_filter.conf` 32 | Packet and device filter configuration 33 | 34 | * `kismet_uav.conf` 35 | Parsing rules for detecting UAV / Drones or similar devices; compiled from the `kismet_uav.yaml` file 36 | 37 | * `kismet_80211.conf` 38 | Configuration settings for Wi-Fi (IEEE80211) specific options 39 | 40 | * `kismet_site.conf` 41 | Optional configuration override; Kismet will load any options in the `kismet_site.conf` file last and they will take precedence over all other configs. 42 | 43 | ### Configuration Format 44 | 45 | Configuration files are plain text. 46 | 47 | Any lines beginning with a `#` are comments, and are ignored. 48 | 49 | Typically, example or default values are provided in comments; to enable or change that option, uncomment the line and set it accordingly - or better yet, put it in your `kismet_site.conf` file, details below. 50 | 51 | Configuration options all take the form of: 52 | `option=value` 53 | 54 | Some configuration options support repeated definitions, such as the 55 | `source` option which defines a Kismet datasource: 56 | `source=wlan0` 57 | `source=wlan1` 58 | 59 | Kismet supports importing config files. This is used by Kismet itself to 60 | split the config files into more readable versions, but can also be used 61 | for including custom options. 62 | 63 | * `include=/path/to/file` 64 | Include a config file; this file is parsed immediately, and the file **must** exist or Kismet will exit with an error. 65 | * `opt_include=/path/to/file` 66 | Include an **optional** config file. If this file does not exist, Kismet will generate a warning, but continue working. 67 | * `opt_override=/path/to/file` 68 | Include an **optional OVERRIDE** config file. This is a special file which is loaded at the **end** of all other configuration. Any configuration options found in an override file **replace all other instances of those configurations**. This is a very powerful mechanism for provisioning multiple Kismet servers or making a config which survives an upgrade and update to the newest configuration files when running from git. 69 | 70 | ### Configuration Override Files - `kismet_site.conf` 71 | If you often upgrade from source (or nightly packages) you may find replacing changes in your config files becomes tedious. To simplify the upgrade process, or building a Kismet install for automatic placement on sensors, changes can be placed in the `kismet_site.conf` config file. 72 | 73 | This file is specified as an OVERRIDE FILE. Any options placed in kismet_site.conf will REPLACE ANY OPTIONS OF THE SAME NAME. Options in this file take precedence over any other options. 74 | 75 | By default, Kismet will look for an optional override file in the default 76 | configuration directory (`/usr/local/etc` for source and `/etc/kismet/` for packages, by default) named `kismet_site.conf`. 77 | 78 | This mechanism allows a site configuration to override any default config 79 | options, while not making changes to any configuration file installed by 80 | Kismet. This allows new installations of Kismet to replace the config files with impunity while preserving a custom configuration. 81 | 82 | Typical uses of this file might include changing the http data directory, 83 | defining sources and memory options, forcing or disabling logging, and so on; a `kismet_site.conf` file might look like: 84 | ``` 85 | server_name=Some server 86 | server_description=Building 2 floor 3 87 | 88 | gps=serial:device=/dev/ttyACM0,name=laptop 89 | 90 | remote_capture_listen=0.0.0.0 91 | remote_capture_port=3501 92 | 93 | source=wlan1:name=SomeServerWlan1 94 | source=wlan2:name=SomeServerWlan2 95 | ``` 96 | 97 | ### Configuration override 'flavors' 98 | 99 | Sometimes you may want to maintain multiple configurations for Kismet, for example with different sources, server names, or logging options. 100 | 101 | This can be easily accomplished with override files and the `--override` option to Kismet. 102 | 103 | Passing `--override {name}` to Kismet will automatically load `kismet_{name}.conf` from the Kismet configuration directory, as an override after all other files (by default the configuration directory is `/usr/local/etc` when compiling from source, or `/etc/kismet` when installing from packages). 104 | 105 | For example, creating `/etc/kismet/kismet_rtl.conf`: 106 | 107 | ``` 108 | server_name=Kismet RTL 109 | 110 | source=rtl433-0 111 | 112 | log_title=KismetRtl433 113 | ``` 114 | 115 | and launching Kismet with: 116 | 117 | ```bash 118 | $ kismet --override rtl 119 | ``` 120 | 121 | would capture only from the first RTL-SDR device as a RTL433 capture, and name the logs KismetRtl433-foo. 122 | 123 | Alternately, a complete path to an override file can be given: 124 | 125 | ```bash 126 | $ kismet --override=/home/foo/some_config.conf 127 | ``` 128 | 129 | Files loaded with the `--override` option will take precedence over all other configuration options, including any changes in `kismet_site.conf`. 130 | 131 | #### Appending in an override 132 | 133 | In certain, relatively rare, instances, it might be required to *append* a value in an override instead of completely replacing it - such as adding the `wiglecsv` log type in the wardrive overlay. Using the `+=` assignment, this is easy! 134 | 135 | ``` 136 | log_types+=wiglecsv 137 | ``` 138 | 139 | This will add to the `log_types` configuration instead of replacing it. 140 | 141 | 142 | -------------------------------------------------------------------------------- /readme/026-packaging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Packaging" 3 | permalink: /docs/readme/packaging/ 4 | excerpt: "Recommendations for package maintainers" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Major changes 10 | 11 | * 2020-07 Moved packaging examples 12 | Moved the distro-specific packaging scripts (docker, openwrt, fpm, centos, etc) into their [own repository](https://github.com/kismetwireless/kismet-packages) 13 | 14 | * 2020-06 Gzipped data files 15 | The manufacturer database is now compressed to reduce space in packages. 16 | * 2020-06 Migration of ADSB ICAO file 17 | The ADSB ICAO registration (lookup file for aircraft registration info) is now in the main Kismet distribution as conf/kismet_adsb_icao.txt.gz, and has been removed from the python3 adsb datasource 18 | * 2020-06 Kismetdb_to_pcap tool 19 | A new conversion tool, kismetdb_to_pcap, is built as part of Kismet in the log_tools/ directory 20 | 21 | * 2020-03 Kismetdb_clean tool 22 | A new kismetdb maintaince tool, kismetdb_clean, is built as part of Kismet in the log_tools/ directory. 23 | 24 | ## Packaging Kismet 25 | 26 | Every distribution is different, and has different idioms for configuration location and style, but we recommend the following where ever possible. 27 | 28 | Example packages for various distributions are in the [kismet-packages](https://github.com/kismetwireless/kismet-packages) repository. 29 | 30 | ### Provide a suid (or setcap) install option 31 | 32 | The Kismet capture binaries (`kismet_cap_linux_wifi`, `kismet_cap_linux_bluetooth`, and so on) require root privileges to control the interfaces, however generally Kismet itself should not be run as root. Kismet supports two mechanisms for this: 33 | 34 | 1. Installing the binaries setuid root, and restricting access to them by limiting them to a specific group (`kismet`, by preference). 35 | 2. Installing the binaries normally, but using `setcap` to give them authority to change network settings: `setcap cap_net_raw,cap_net_admin=eip`, and restricting them to a single group (`kismet` again, by preference). 36 | 37 | When installed suid-root, the Kismet helper utilities will drop capabilities and pivot into a read-only mount namespace. 38 | 39 | ### Provide multiple packages for capture tools 40 | 41 | Kismet capture tools can be packaged independently. By preference, the capture tools should be independent packages so that a user building a remote capture system only needs the specific capture packages. A meta-package which references all of the capture tools can provide a simple installation point for users. 42 | 43 | ### Default prefix 44 | 45 | The Kismet configure defaults to `/usr/local/`; typically a distribution package would target `/usr` as the prefix. This can be adjusted as per LSB and distribution guidelines. 46 | 47 | ### Data files 48 | 49 | Kismet installs data and lookup files to `${prefix}/share/kismet/`; these include `kismet_manuf.txt.gz` and `kismet_adsb_icao.txt.gz` and in the future will include similar files for Bluetooth service resolution. 50 | 51 | The manuf file should, if possible, always be installed - this is the lookup database for manufacturer assignments based on MAC address. For *extremely* size constrained distributions this file could be omitted (preferably moved to its own package so that a user can choose to install it), however the user experience will be degraded. 52 | 53 | The ICAO file is particularly large (6+ MB, gzipped). This file is used to resolve the FAA ICAO registration for ADSB. In the main Kismet packages, this is installed as a by-default included, but independent, package. For any platform where storage is a concern, this file can be split into an independent package. The user experience will only be impacted if the user is using a SDR to capture ADSB airplane data. 54 | 55 | ### Config files 56 | 57 | Kismet looks for config files in the directory specified in `configure` via the `--sysconfdir` directive. This location may vary per distribution, however typically `/etc/kismet` would be the appropriate default, and is the location used by the packages provided on the Kismet site. 58 | 59 | #### Use `kismet_package.conf` 60 | 61 | When building packages for tiny systems, like under OpenWRT, you can include a `kismet_package.conf` in your package; the default Kismet configs will first load the Kismet configuration files, then, if present, a `kismet_package.conf` configuration file which will override any options specified, and finally, `kismet_site.conf` which will override any previous settings. 62 | 63 | This setup allows tuning Kismet automatically for inclusion on some systems, while removing the need to maintain patches to the base Kismet configs. 64 | 65 | `kismet_package.conf` should be placed in the configuration directory with the other Kismet configs. 66 | 67 | #### Never override `kismet_site.conf` 68 | 69 | Kismet provides an override mechanism for local configurations which take precedence over all other config options; these are kept in `kismet_site.conf` by default. A package should never provide this file, as changes made by the user will likely go here. You can auto-configure options via `kismet_package.conf` however. 70 | 71 | ### Package log tools 72 | 73 | Kismet provides a suite of tools for interacting with the kismetdb logs (built in the `log_tools/` directory). Typically it would make sense to make a package encompassing the suite of tools rather than build them as part of the core package. 74 | 75 | ### Protobuf-lite 76 | 77 | Some distributions (like OpenWRT) use libprotobuf-lite to save space. Kismet does not use any of the options removed in the lite version, but *should* be configured with the `--enable-protobufite` option to `./configure`. 78 | 79 | -------------------------------------------------------------------------------- /readme/030-config_logging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Logging" 3 | permalink: /docs/readme/logging/ 4 | excerpt: "Kismet has many logging options; here's how to pick which options you need." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Logging 10 | 11 | Kismet supports logging to multiple file types: 12 | 13 | * `kismet` is the primary log format now used by Kismet. This log combines all the data Kismet is able to gather - packets, device records, alerts, system messages, GPS location, non-packet received data, and more. This file can be manipulated with the tools in the `log_tools/` directory. Under the covers, a `kismet` log is a sqlite3 database. 14 | * `pcapppi` is the legacy pcap format using the PPI headers. This format saves Wi-Fi packets, GPS information, and *some* (but not all) of the signal information per packet. Information about which datasource captured a packet is not preserved. 15 | * `pcapng` is the modern pcap format. While not all tools support it, Wireshark and TShark have excellent support. Most tools written using libpcap can read pcap-ng files with a *single* data source. When using pcap-ng, Kismet can log packets from multiple sources, preserving the datasource information and the original, complete, per-packet signal headers. 16 | 17 | ### Picking a log format 18 | 19 | Kismet can log to multiple logs simultaneously, configured in the `kismet_logging.conf` config file (or in the `kismet_site.conf` override configuration). Logs are configured by the `log_types=` config option, and multiple types can be specified: 20 | 21 | ``` 22 | log_types=kismet,pcapng 23 | ``` 24 | 25 | ### Log names and locations 26 | 27 | Log naming and location is configured in `kismet_logging.conf` (or `kismet_site.conf` for overrides). Logging can be disabled entirely with: 28 | 29 | ``` 30 | logging_enabled=false 31 | ``` 32 | 33 | or it can be disabled at launch time by launching Kismet with `-n`: 34 | 35 | ```bash 36 | $ kismet -n ... 37 | ``` 38 | 39 | 40 | The default log title is 'Kismet'. This can be changed using the `log_title=` option: 41 | 42 | ``` 43 | log_title=SomeCustomName 44 | ``` 45 | 46 | or it can be changed at launch time by running Kismet with `-t ...`: 47 | 48 | ```bash 49 | $ kismet -t SomeCustomeName ... 50 | ``` 51 | 52 | Kismet stores logs in the directory it is launched from. This can be changed using the `log_prefix=` option; this is most useful when launching Kismet as a service from systemd or similar when the directory it is being launched from may not be where you want to store logs: 53 | 54 | ``` 55 | log_prefix=/tmp/kismet 56 | ``` 57 | 58 | -------------------------------------------------------------------------------- /readme/031-logging_kismetdb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Logging" 3 | permalink: /docs/readme/logging_kismetdb/ 4 | excerpt: "Kismet unified logging format" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Kismetdb logging 10 | 11 | The `kismet` log format is a unified common log of packets, non-packet data, devices, location, system messages, datasource records, historical trends, and almost everything else Kismet can track. It replaces the legacy logs where multiple log files were needed to reconstruct history. 12 | 13 | The `kismet` log file cam be converted to many other log types using the associated log tools, including pcap, pcapng, wiglecsv, json records, KML, and more. 14 | 15 | ### Log type 16 | 17 | ``` 18 | log_types=kismet 19 | ``` 20 | 21 | ### Kismet log journal files 22 | 23 | The `kismet` log format uses sqlite3 to create a dynamic random-access file. If Kismet exits abnormally (such as running out of RAM or the power to the device failing), it may leave behind a `...-journal` file. 24 | 25 | This file is part of the sqlite3 integrity protection, and contains partial data which was not written to the database. 26 | 27 | The journal file will be automatically merged when the log file is opened, or you can manually merge them with sqlite command line tools: 28 | 29 | ```bash 30 | $ sqlite3 Kismet-foo-whatever.kismet 'VACUUM;' 31 | ``` 32 | 33 | or via the included Kismet log cleanup tool: 34 | 35 | ```bash 36 | $ kismetdb_clean foo.kismet 37 | ``` 38 | 39 | ### Kismetdb ephemeral and timed logs 40 | 41 | The `kismet` log format can be used as an ephemeral (non-permanent) log file, and can automatically time-limit the data. This is extremely useful if you are using Kismet as a stand-alone sensor, where the data is being collected over the REST interface. 42 | 43 | Kismetdb logs can be automatically purged of old data. The timeout values are in seconds - `60 * 60 * 24`, which is `86400`, sets a 24 hour timeout on data. 44 | 45 | ``` 46 | kis_log_alert_timeout=86400 47 | kis_log_device_timeout=86400 48 | kis_log_message_timeout=86400 49 | kis_log_packet_timeout=86400 50 | kis_log_snapshot_timeout=86400 51 | ``` 52 | 53 | Data in each of the categories is *removed from the kismetdb log file* after the timeout. Devices which have been idle for more than the `kis_log_device_timeout` are removed. 54 | 55 | A kismetdb log may be marked as *ephemeral* by setting: 56 | 57 | ``` 58 | kis_log_ephemeral_dangerous=true 59 | ``` 60 | 61 | An ephemeral log is removed from the filesystem upon creation; the log is not accessible on disk, and will be removed immediately upon Kismet exiting. Ephemeral logs are most useful when deploying Kismet as a permanent fixed sensor with a time-limited history; for instance retaining the past day of devices, packets, etc, but where there is no need (or desire) to keep log files. 62 | 63 | ## Filtering 64 | 65 | Kismet can filter packets and devices logged in the `kismetdb` log file. This can be used to exclude known devices, or include ONLY certain types of devices and packets. 66 | 67 | Filtering is most useful when coupled with other tools, and most users won't need to worry about it, but can be a powerful tool in specific situations. 68 | 69 | ### Duplicate packets 70 | 71 | Kismet can record duplicate packets when multiple datasources capture the same data. In some instances, keeping duplicate packets is desirable (such as remote captures used for device location), while in others, logging duplicates may be a waste of space. 72 | 73 | ``` 74 | kismetdb_log_duplicate_packets=false 75 | ``` 76 | 77 | ### Data packets 78 | 79 | Kismet typically logs all types of packets. To discard data packets, retaining only management frames: 80 | 81 | ``` 82 | kismetdb_log_data_packets=false 83 | ``` 84 | 85 | ### Pass and block modes 86 | Kismet filters operate as `pass` or `block`. Events which are `passed` are allowed to be logged, while events which are `blocked` are excluded. 87 | 88 | ### Default and match modes 89 | Kismet filters have a default mode: if a record does not match any other filter, the default mode is applied. 90 | 91 | Records can match a pass or block mode before reaching the default mode. A filter with a default of `block` can still allow specific records through with a matching `pass` element. 92 | 93 | ### Group matches 94 | 95 | MAC addresses can be specified as a single address `AA:BB:CC:DD:EE:FF`, or as a masked group `11:22:33:00:00:00/FF:FF:FF:00:00:00`. 96 | 97 | A masked group works like an IP netmask specification: the value after the `/` indicates the bytes to match on; in the case above, the match will grab any MAC address beginning with `11:22:33:...`. 98 | 99 | The most common use for masked matching is to match OUIs which are the first 3 bytes of the MAC address. 100 | 101 | ### Device filters 102 | 103 | Filtering device records from the `kismetdb` log will not prevent Kismet from showing them, but prevents Kismet from logging them. 104 | 105 | Devices are filtered by phyname and mac address. Mac addresses can be specified as a single MAC or as a masked group. 106 | 107 | The default filter controls are in `kismet_filter.conf`. 108 | 109 | * `kis_log_device_filter_default=pass | block` 110 | By default, kismetdb logs are not filtered, and the default for devices is `pass`. 111 | 112 | * `kis_log_device_filter=phyname,macaddress,value` 113 | Adds a device filter for the given phyname and MAC address. For example: 114 | `kis_log_device_filter=IEEE802.11,aa:bb:cc:dd:ee:ff,pass` 115 | `kis_log_device_filter=IEEE802.11,00:11:22:00:00:00/ff:ff:ff:ff:ff:ff,block` 116 | 117 | ### Packet filters 118 | 119 | Filtering packets from the `kismetdb` log will not prevent Kismet from processing them and creating related devices, but will prevent the actual packet data from being logged. 120 | 121 | Packets can be filtered based on the MAC address of the source, destination, network, or 'other' address. For Wi-Fi, the 'other' address is used only in WDS environments where the quad-MAC headers are used. Packet filters may also filter on 'any' address, which matches any of the four. 122 | 123 | The default filter controls are in `kismet_filter.conf`. 124 | 125 | * `kis_log_packet_filter_default=pass | block` 126 | By default, kismetdb logs are not filtered, and the default for packets is `pass`. 127 | 128 | * `kis_log_packet_filter=phyname,addresstype,macaddress,value` 129 | Adds a packet filter for the given phyname, address type (source, destination, network, other, any), and MAC address. For example: 130 | `kis_log_packet_filter=IEEE802.11,source,aa:bb:cc:dd:ee,pass` 131 | `kis_log_packet_filter=IEEE802.11,any,00:11:22:00:00:00/ff:ff:ff:ff:ff:ff,block` 132 | 133 | ### Live filter control 134 | Packet filters can be enabled and manipulated live via the [filter REST API](/docs/devel/webui_rest/filters/). 135 | 136 | -------------------------------------------------------------------------------- /readme/031-logging_pcap.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Pcap logging" 3 | permalink: /docs/readme/logging_pcap/ 4 | excerpt: "Pcap logging format" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Pcap logging 10 | 11 | Pcap (and pcapng) are standard formats for logging packets, which most tools which manipulate packets accept, including Tcpdump and Wireshark. A kismetdb log can be converted to pcapng, or Kismet can write pcap logs directly. 12 | 13 | There are two main flavors of pcap supported by Kismet: 14 | 15 | 1. `pcapppi` 16 | 17 | `pcapppi` is the legacy pcap format, with the PPI headers. This version of the pcap log can only handle Wi-Fi packets, and manipulates the packet headers to fit the PPI standard (only one antenna signal value and other limitations). Generally the `pcapng` format should be used, but not all tools understand the new format. 18 | 19 | 2. `pcapng` 20 | 21 | `pcapng` is the modern pcap standard supported by wireshark, tshark, and other tools. 22 | 23 | Pcap-ng allows for mixing packet types (such as Wi-Fi, BTLE, and Zigbee) as well as retaining the original capture interface (which datasource in Kismet saw the packet), the original headers (pure radiotap packet headers with more complete signal info, timestamps, etc). It also allows Kismet to log the packet without manipulation (such as header translation to PPI), allows for annotations, other data, and more. 24 | 25 | ### Log type 26 | 27 | ``` 28 | log_types=pcapppi 29 | ``` 30 | 31 | and 32 | 33 | ``` 34 | log_types=pcapng 35 | ``` 36 | 37 | 38 | ## Filtering 39 | 40 | ### Duplicate packets 41 | 42 | Kismet can record duplicate packets when multiple datasources capture the same data. In some instances, keeping duplicate packets is desirable (such as remote captures used for device location), while in others, logging duplicates may be a waste of space. 43 | 44 | ``` 45 | pcapng_log_duplicate_packets=false 46 | ``` 47 | 48 | and 49 | 50 | ``` 51 | ppi_log_duplicate_packets=false 52 | ``` 53 | 54 | ### Data packets 55 | 56 | Kismet typically logs all types of packets. To discard data packets, retaining only management frames: 57 | 58 | ``` 59 | pcapng_log_data_packets=false 60 | ``` 61 | 62 | and 63 | 64 | ``` 65 | ppi_log_data_packets=false 66 | ``` 67 | 68 | -------------------------------------------------------------------------------- /readme/031-logging_wiglecsv.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Wigle logging" 3 | permalink: /docs/readme/logging_wigle/ 4 | excerpt: "Wigle logging format" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Wigle logging 10 | 11 | Kismet can convert a `kismetdb` log to a CSV format suitable to upload to [Wigle](https://wigle.net), but can also directly write a `wiglecsv` file. 12 | 13 | ### Log type 14 | 15 | ``` 16 | log_types=wiglecsv 17 | ``` 18 | 19 | ### Wiglecsv 20 | 21 | A Wigle log does not contain packet data - it is a simplified CSV file of Wi-Fi access points and Bluetooth devices. 22 | 23 | Since Wigle is centered around mapping wireless, Kismet will only create entries in the `wiglecsv` log when a GPS is connected and a location is available. 24 | -------------------------------------------------------------------------------- /readme/045-datasources_bluetooth.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Bluetooth sources" 3 | permalink: /docs/readme/datasources_bluetooth/ 4 | excerpt: "Bluetooth datasources capture BT and BTLE scanning and advertised data." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Bluetooth 10 | Bluetooth uses a frequency-hopping system with dynamic MAC addresses and other oddities - this makes sniffing it not as straightforward as capturing Wi-Fi. 11 | 12 | ### Datasource: Linux HCI Bluetooth 13 | 14 | Kismet can use the generic Linux HCI interface for Bluetooth discovery; this uses a generic Bluetooth adapter to perform *active scans* for discoverable Bluetooth classic and BTLE devices. This is an active scan, not passive monitoring, and reports attributes and advertised information, not packets. 15 | 16 | The Linux Bluetooth source will auto-detect supported interfaces by querying the bluetooth interface list. It can be manually specified with `type=linuxbluetooth`. 17 | 18 | The Linux Bluetooth capture uses the 'kismet_cap_linux_bluetooth' tool, and should typically be installed suid-root: Linux requires root to manipulate the `rfkill` state and the management socket of the Bluetooth interface. 19 | 20 | #### Example source 21 | ``` 22 | source=hci0:name=linuxbt 23 | ``` 24 | 25 | #### Supported Hardware 26 | 27 | For simply identifying Bluetooth (and BTLE) devices, the Linux Bluetooth datasource can use any standard Bluetooth interface supported by Linux. 28 | 29 | This includes almost any built-in Bluetooth interface, as well as external USB interfaces such as the Sena UD100. 30 | 31 | This datasource is available *only* on Linux. 32 | 33 | #### Service Scanning 34 | 35 | By default, the Kismet Linux Bluetooth data source turns on the Bluetooth interface and enables scanning mode. This allows it to see broadcasting Bluetooth (and BTLE) devices and some basic information such as the device name, but does not allow it to index services on the device. 36 | 37 | Complex service scanning and enumeration will be coming in a future revision. 38 | 39 | #### Bluetooth Source Parameters 40 | Linux Bluetooth sources support all the common configuration options such as name, information elements, and UUID. 41 | 42 | ### Datasource: Ubertooth One (BTLE) 43 | 44 | The Ubertooth One is an open-source hardware Bluetooth and BTLE sniffer by Great Scott Gadgets. 45 | 46 | Kismet must be compiled with support for `libusb`, `libubertooth`, and `libbtbb`; you will need `libusb-1.0-dev`, `libubertooth-dev`, and `libbtbb-dev` (or the equivalents for your distribution), and you will need to make sure that the `Ubertooth` option is enabled in the output from `./configure`. 47 | 48 | #### Ubertooth interfaces 49 | 50 | The Ubertooth One in Kismet can be referred to as simply `ubertooth`: 51 | 52 | ```bash 53 | $ kismet -c ubertooth 54 | ``` 55 | 56 | When using multiple Ubertooth (Uberteeth?) devices, each device is numbered, starting from 0. The Ubertooth library indexes the devices automatically, and so is dependent on the order the devices were detected. 57 | 58 | ```bash 59 | $ kismet -c ubertooth-1 60 | ``` 61 | 62 | Kismet will list available Ubertooth devices automatically in the datasources list. 63 | 64 | #### Limitations 65 | 66 | The Ubertooth One truncates all packets to a maximum of 50 bytes; packets larger than 50 bytes will be discarded and ignored because it is not possible to validate the checksum. 67 | 68 | The Ubertooth One firmware (as of 2019-12) appears to have issues setting channels in BTLE mode, leading to frequent firmware crashes which require the USB device to be removed and re-inserted. Kismet currently disables channel hopping on the Ubertooth One, and defaults to advertising channel 37. 69 | 70 | Alternate channels can be set with the `channel=` source option; 71 | 72 | ```bash 73 | $ kismet -c ubertooth:channel=39 74 | ``` 75 | 76 | To try to mitigate firmware hangs, Kismet will reset the U1 device periodically, which will reboot the U1. This does not prevent all firmware hangs, however, and you may find it necessary to remove and re-insert the Ubertooth One periodically. 77 | 78 | #### Supported Hardware 79 | 80 | This datasource works with the [Ubertooth One by Great Scott Gadgets](https://greatscottgadgets.com/ubertoothone/). 81 | 82 | This datasource should work on any platform, so long as the appropriate libraries are available. 83 | 84 | ### Datasource - TI CC2540 (BTLE) 85 | 86 | The Texas Instruments CC2540 is a chip used for Bluetooth communications. To use it with Kismet, it must be flashed with the sniffer firmware [provided by TI](http://www.ti.com/tool/PACKET-SNIFFER). Often the devices are available with the sniffer firmware pre-flashed. 87 | 88 | Kismet must be compiled with support for `libusb` to use TICC2540; you will need `libusb-1.0-dev` (or the equivalent for your distribution), and you will need to make sure that the `TI CC 2540` option is enabled in the output from `./configure`. 89 | 90 | To use the TI CC2540 capture, you must have a TI CC2540 dongle flashed with the sniffer firmware. You can flash this yourself with a CC-Debugger or purchase one online from many retailers. 91 | 92 | *Note*: It seems that while many CC2540 devices are *advertised* as pre-flashed with the sniffer firmware, they appear not to be! 93 | 94 | #### TI CC2540 shortcomings 95 | 96 | The sniffer firmware in the TI CC2540 sometimes goes into a permanent error state until the device is physically re-initialized - by disconnecting it from USB and reconnecting it. Unfortunately, there does not seem to be any way to automate this process, as once the device enters an error state, it will remain in that state and cannot be reinitialized over USB. 97 | 98 | #### TI CC2540 interfaces 99 | 100 | TI CC2540 datasources in Kismet can be referred to as simply `ticc2540-...`: 101 | 102 | ```bash 103 | $ kismet -c ticc2540-0 104 | ``` 105 | 106 | When using multiple TICC devices, they can be specified either in order discovered by the system (`ticc2540-0`, `ticc2540-1`, etc), or by USB path. If you need to know which specific device is being configured, use the USB path - however, this path may be subject to change if USB devices are moved, new USB devices added, etc. 107 | 108 | To find the location on the USB bus, look at the output of the command `lsusb`: 109 | 110 | ```bash 111 | $ lsusb 112 | ... 113 | Bus 001 Device 008: ID 0451:16b3 Texas Instruments, Inc. 114 | Bus 005 Device 004: ID 0451:16b3 Texas Instruments, Inc. 115 | Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub 116 | ... 117 | ``` 118 | 119 | In this instance the first device is on `bus 001` and `device 008` and the second device is on `bus 005` and `device 004`; we can specify this specific first device in Kismet by using: 120 | 121 | ```bash 122 | $ kismet -c ticc2540-1-8 123 | ``` 124 | 125 | Be sure that you are looking at the proper devices - many USB devices have similar vendor IDs! 126 | 127 | Kismet will also list available TI CC2540 devices automatically in the datasources list. 128 | 129 | #### Supported Hardware 130 | 131 | Any USB device based on the CC2540 chip, and flashed with the TI sniffer firmware, should work. Beware! Many online vendors sell identical-looking devices based on the CC2531 chip, which is *not* the same thing! 132 | 133 | This datasource should work on any platform, so long as the appropriate libraries are available. 134 | 135 | ### Datasource - nRF 51822 (BTLE) 136 | 137 | The nRF 51822 is a chip used for Bluetooth LE communications. To use it with Kismet, it must be flashed with sniffer firmware provided by NordicRF. A pre-flashed version is available from Adafruit and other online retailers. 138 | 139 | The nRF 51822 utilizes serial communications so no special libraries are needed for use with Kismet, *however* not all platforms have working serial port drivers (see below). 140 | 141 | #### nRF 51822 interfaces 142 | 143 | nRF 51822 datasources in Kismet can be referred to as simply `nrf51822`. These devices appear as serial ports, so cannot be auto-detected. Each nrf51822 source must have a `device` option: 144 | 145 | ```bash 146 | source=nrf51822:device=/dev/ttyUSB0 147 | ``` 148 | 149 | #### Channel Hopping 150 | 151 | The firmware does it's own channel hopping so no selections are available. 152 | 153 | #### Limitations 154 | 155 | You must specify a `device=` configuration pointing to the serial port this device has been assigned by the kernel; it can not be automatically detected, and will not appear in the datasource list. 156 | 157 | Multiple versions of the Adafruit BLE device are sold, and not all have the sniffer firmware. Make sure you have a V2 or newer device, *with the sniffer firmware*. 158 | 159 | Devices without sniffer firmware *may* be flashable, but may require an external programmer. 160 | 161 | #### MacOS Limitations 162 | 163 | The nRF 51822 uses a CP2104 serial chip; testing with the [latest drivers](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) under MacOS Catalina has been unsuccessful; however a driver update may fix that in the future. 164 | 165 | -------------------------------------------------------------------------------- /readme/050-datasources_pcapfile.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Pcap capture file source" 3 | permalink: /docs/readme/datasources_pcapfile/ 4 | excerpt: "Pcap datasources replay existing pcap files as if they were live data" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Replaying data 10 | Kismet can replay recorded data in the `pcap` and `pcap-ng` formats. Pcap files are commonly generated by tools like `tcpdump`, `wireshark`, `tshark`, and Kismet itself. 11 | 12 | Kismet can replay a pcapfile for testing, debugging, demo, or reprocessing. 13 | 14 | ### Datasource - Pcapfile 15 | 16 | The Pcapfile datasource will auto-detect pcap files and paths to files: 17 | ```bash 18 | $ kismet -c /tmp/foo.pcap 19 | ``` 20 | 21 | It can be manually specified with `type=pcapfile`, as in: 22 | 23 | ``` 24 | source=/tmp/foo.pcap:type=pcapfile 25 | ``` 26 | 27 | The pcapfile capture uses the 'kismet_cap_pcapfile' tool which does not need special privileges. 28 | 29 | Currently Kismet supports pcap-ng files with a single interface in the capture; multi-interface captures will appear as coming from a single data source - that of the pcapfile itself. 30 | 31 | ### Pcapfile Options 32 | In addition to the normal options supported by all sources (name, information elements, UUID, etc) the pcapfile source can also support: 33 | 34 | * `pps=rate` 35 | Normally, pcapfiles are replayed as quickly as possible. On larger pcaps this can lead to CPU and RAM contention, and dropped packets. Specifying a packets-per-second rate throttles processing of the packet to a more sustainable speed. 36 | This option cannot be combined with the `realtime` option. 37 | 38 | * `realtime=true | false` 39 | Normally, pcapfiles are replayed as quickly as possible. On larger pcaps this can lead to CPU and RAM contention, and dropped packets. Specifying `realtime=true` in your source definition will reduce the packet processing rate to the original capture rate, and the packets will be processed with real-time delays equal to how they were received. 40 | 41 | These options can be used in the kismet.conf and kismet_site.conf, as in: 42 | 43 | ``` 44 | source=/tmp/foo.pcap:type=pcapfile,name=a_meaningful_name,realtime=true 45 | ``` 46 | 47 | Or from the command line: 48 | 49 | ```bash 50 | $ kismet -c /tmp/foo.pcap:name=a_meaningful_name,pps=1000 51 | ``` 52 | 53 | 54 | 55 | -------------------------------------------------------------------------------- /readme/051-datasources_kismetdb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "KismetDB file source" 3 | permalink: /docs/readme/datasources_kismetdb/ 4 | excerpt: "Kismetdb datasources replay kismet log files." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Replaying data 10 | Added: 2019-03 11 | 12 | Kismet can replay recorded data in the `kismetdb` format, the unified log created by Kismet. 13 | 14 | Kismet can replay a pcapfile for testing, debugging, demo, or reprocessing. 15 | 16 | A `kismetdb` file can contain packets and device data from any source Kismet handles. 17 | 18 | ### Datasource - kismetdb 19 | 20 | The kismetdb datasource will auto-detect kismetdb files and paths to files: 21 | ```bash 22 | $ kismet -c /tmp/foo.kismet 23 | ``` 24 | 25 | It can be manually specified with `type=kismetdb`, as in: 26 | 27 | ``` 28 | source=/tmp/foo.kismet:type=kismetdb 29 | ``` 30 | 31 | The kismetdb capture uses the 'kismet_cap_kismetdb' tool which does not need special privileges. 32 | 33 | When replying a kismetdb file, data from multiple interfaces will appear as though it is from a single capture source - the kismetdb file. 34 | 35 | ### Kismetdb Options 36 | In addition to the normal options supported by all sources (name, information elements, UUID, etc) the kismetdb source can also support: 37 | 38 | * `pps=rate` 39 | Normally, kismetdb files are replayed as quickly as possible. On larger logs this can lead to CPU and RAM contention, and dropped packets. Specifying a packets-per-second rate throttles processing of the packet to a more sustainable speed. 40 | This option cannot be combined with the `realtime` option. 41 | 42 | * `realtime=true | false` 43 | Normally, kismetdb files are replayed as quickly as possible. On larger logs this can lead to CPU and RAM contention, and dropped packets. Specifying `realtime=true` in your source definition will reduce the packet processing rate to the original capture rate, and the packets will be processed with real-time delays equal to how they were received. 44 | 45 | These options can be used in the kismet.conf and kismet_site.conf, as in: 46 | 47 | ``` 48 | source=/tmp/foo.kismet:type=kismetdb,name=a_meaningful_name,realtime=true 49 | ``` 50 | 51 | Or from the command line: 52 | 53 | ```bash 54 | $ kismet -c /tmp/foo.kismet:name=a_meaningful_name,pps=1000 55 | ``` 56 | 57 | 58 | 59 | -------------------------------------------------------------------------------- /readme/055-datasources_sdr_rtl433.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "SDR rtl433 sources" 3 | permalink: /docs/readme/datasources_sdr_rtl433/ 4 | excerpt: "SDR-based rtl433 sources use the rtl-sdr radio to capture a wide range of sensors, thermometers, and switches." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Datasource - SDR RTL433 10 | 11 | The rtl-sdr radio is an extremely cheap USB SDR (software defined radio). While very limited, it is still capable of performing some useful monitoring. 12 | 13 | Kismet is able to process data from the rtl_433 tool, which can read the broadcasts of a multitude of wireless thermometer, weather, electrical, tire pressure, and other sensors. 14 | 15 | To use the rtl433 capture, you must have a rtl-sdr USB device; this cannot be done with normal Wi-Fi hardware because a Wi-Fi card is not able to tune to the needed frequencies, and cannot report raw radio samples that are not Wi-Fi packets. 16 | 17 | More information about the rtl-sdr is available at: https://www.rtl-sdr.com 18 | 19 | The rtl_433 tool can be downloaded from: https://github.com/merbanan/rtl_433 or as a package in your distribution. 20 | 21 | The Kismet rtl_433 interface uses librtlsdr, rtl_433, and Python; rtl433 sources will show up as normal Kismet sources using the rtl433-X naming. 22 | 23 | ### rtl433 devices 24 | 25 | Kismet identifies rtl433 hardware by either the serial number (if any) or by the radio position; for example: 26 | 27 | The first rtl433 radio in the system: 28 | 29 | `source=rtl433-0` 30 | 31 | A specific rtl433 radio (if serial numbers are available): 32 | 33 | `source=rtl433-324452324332` 34 | 35 | Not all rtl433 hardware populates the serial number field. 36 | 37 | Serial numbers can be found using the standard rtlsdr tools, like `rtl_test`: 38 | 39 | ```bash 40 | $ rtl_test 41 | Found 4 device(s): 42 | 0: NooElec, NESDR Nano 3, SN: 2686186936 43 | 1: NooElec, NESDR Nano 3, SN: 1177459274 44 | 2: NooElec, NESDR Nano 3, SN: 2664167682 45 | 3: NooElec, NESDR Nano 3, SN: 0572734167 46 | ``` 47 | 48 | ### Using multiple rtlsdr devices 49 | 50 | Every datasource in Kismet must have a unique identifier, the source UUID. Kismet calculates this using the serial number of the rtlsdr device. 51 | 52 | Not all rtlsdr hardware supplies a valid serial number; often devices will report a serial number of "00000000". This will not cause any problems for Kismet if it is the only rtlsdr device, however when using multiple rtlsdr radios either locally or via remote capture, each one must have a unique ID. 53 | 54 | A unique ID can be set using the `rtl_eeprom` tool to assign a proper serial number, or by using the `uuid=...` parameter on the Kismet source definition. A unique UUID can be generated with the `genuuid` tool on most systems. 55 | 56 | ### rtl433 parameters 57 | 58 | RTL433 sources accept several options in the source definition, in addition to the common name, informational, and UUID elements: 59 | 60 | * `channel=xyz` 61 | 62 | Manually set the frequency; by default rtl433 tunes to `433.920MHz`. 63 | 64 | Frequency can be in MHz: 65 | 66 | `source=rtl433-0:channel=400MHz` 67 | 68 | or KHz: 69 | 70 | `source=rtl433-0:channel=500000KHz` 71 | 72 | or raw hz: 73 | 74 | `source=rtl433-0:channel=512000000` 75 | 76 | * `ppm_error=xyz` 77 | 78 | Set the error correction level for your radio, passed as the `-p` option to rtl433 79 | 80 | * `gain=xyz` 81 | 82 | Set the gain, if supported, passed as the `g` option to rtl433 83 | 84 | -------------------------------------------------------------------------------- /readme/056-datasources_sdr_rtlamr.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "SDR rtlamr sources" 3 | permalink: /docs/readme/datasources_sdr_rtlamr/ 4 | excerpt: "SDR-based rtlamr sources use the rtl-sdr radio to capture AMR based power and water meter readings." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | *Updated for Kismet 2019-10* 10 | 11 | ## RTL-AMR 12 | 13 | To capture AMR with Kismet, you'll need a rtl-sdr USB software defined radio. You can't capture these signals with a Wi-Fi card; they're very different! 14 | 15 | Using a rtl-sdr, Kismet is able to capture the usage readings from AMR-enabled meters. These often include electricity, water, and gas meters. The AMR broadcast is used as part of the meter reading system which allows the utility company to read power usage from the street. 16 | 17 | ### Datasource - SDR RTLAMR 18 | 19 | You will need a python3 environment and the `numpy` package, either installed via `pip3` or as a system package. 20 | 21 | The rtlamr datasource will auto-detect supported rtl-sdr hardware. It can be manually specified with `type=rtlamr`. 22 | 23 | If you have multiple rtl-sdr radios, you can select which radio to use either by radio number (the order it was seen on your system), or by the serial number of the radio; for instance: 24 | 25 | ``` 26 | source=rtlamr-0,name=FirstRadio 27 | ``` 28 | 29 | or 30 | 31 | ``` 32 | source=rtlamr-124334,name=SomeOtherRadio 33 | ``` 34 | 35 | ### Using multiple rtlsdr devices 36 | 37 | Every datasource in Kismet must have a unique identifier, the source UUID. Kismet calculates this using the serial number of the rtlsdr device. 38 | 39 | Not all rtlsdr hardware supplies a valid serial number; often devices will report a serial number of "00000000". This will not cause any problems for Kismet if it is the only rtlsdr device, however when using multiple rtlsdr radios either locally or via remote capture, each one must have a unique ID. 40 | 41 | A unique ID can be set using the `rtl_eeprom` tool to assign a proper serial number, or by using the `uuid=...` parameter on the Kismet source definition. A unique UUID can be generated with the `genuuid` tool on most systems. 42 | 43 | ### Rtl AMR Source Parameters 44 | 45 | RTLAMR sources accept several additional options, in addition to the standard name, informational, and UUID options: 46 | 47 | * `biastee=true | false` 48 | 49 | Enable bias-tee power on supported radios. Bias-tee is used to supply power to external amplifiers or other equipment in the antenna chain, and requires your radio have support for it. 50 | 51 | * `channel=frequency_in_hz` 52 | 53 | Manually force a different frequency; by default the standard of 912.6MHz is used. 54 | 55 | * `gain=value` 56 | 57 | Specifiy a fixed gain level for the radio; by default, the hardware automatic gain control is used. 58 | 59 | * `ppm=error_value` 60 | 61 | Specify a PPM error offset for fine-tuning your radio, if your hardware has a known offset. 62 | 63 | -------------------------------------------------------------------------------- /readme/057-datasources_sdr_rtladsb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "SDR rtladsb sources" 3 | permalink: /docs/readme/datasources_sdr_rtladsb/ 4 | excerpt: "SDR-based rtladsb sources use the rtl-sdr radio to capture airplane ADSB/Mode-S location and telemetry packets." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | *Updated for Kismet 2019-10* 10 | 11 | ## RTL-ADSB 12 | 13 | To capture ADSB with Kismet, you'll need a rtl-sdr USB software defined radio. You can't capture these signals with a Wi-Fi card; they're very different! 14 | 15 | Using a rtl-sdr, Kismet is able to process the transponder data transmitted from commercial aircraft; for more information about the ADSB signal; for more information about the ADSB signal and how to decode it, check out the [mode-s introduction](https://mode-s.org/decode/adsb/introduction.html). 16 | 17 | ### Datasource - SDR RTLADSB 18 | 19 | You will need a python3 environment and the `numpy` package, either installed via `pip3` or as a system package. 20 | 21 | The rtladsb datasource will auto-detect supported rtl-sdr hardware. It can be manually specified with `type=rtladsb`. 22 | 23 | If you have multiple rtl-sdr radios, you can select which radio to use either by radio number (the order it was seen on your system), or by the serial number of the radio; for instance: 24 | 25 | ``` 26 | source=rtladsb-0,name=FirstRadio 27 | ``` 28 | 29 | or 30 | 31 | ``` 32 | source=rtladsb-124334,name=SomeOtherRadio 33 | ``` 34 | 35 | ### Using multiple rtlsdr devices 36 | 37 | Every datasource in Kismet must have a unique identifier, the source UUID. Kismet calculates this using the serial number of the rtlsdr device. 38 | 39 | Not all rtlsdr hardware supplies a valid serial number; often devices will report a serial number of "00000000". This will not cause any problems for Kismet if it is the only rtlsdr device, however when using multiple rtlsdr radios either locally or via remote capture, each one must have a unique ID. 40 | 41 | A unique ID can be set using the `rtl_eeprom` tool to assign a proper serial number, or by using the `uuid=...` parameter on the Kismet source definition. A unique UUID can be generated with the `genuuid` tool on most systems. 42 | 43 | ### Rtl ADSB Source Parameters 44 | RTLADSB sources accept several additional options, in addition to the standard name, informational, and UUID options: 45 | 46 | * `biastee=true | false` 47 | 48 | Enable bias-tee power on supported radios. Bias-tee is used to supply power to external amplifiers or other equipment in the antenna chain, and requires your radio have support for it. 49 | 50 | * `channel=frequency_in_hz` 51 | 52 | Manually force a different frequency; by default the international standard of 1090MHz is used. 53 | 54 | * `gain=value` 55 | 56 | Specifiy a fixed gain level for the radio; by default, the hardware automatic gain control is used. 57 | 58 | * `ppm=error_value` 59 | 60 | Specify a PPM error offset for fine-tuning your radio, if your hardware has a known offset. 61 | 62 | -------------------------------------------------------------------------------- /readme/060-datasources_mousejack.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "nRF Mousejack sources" 3 | permalink: /docs/readme/datasources_nrf_mousejack/ 4 | excerpt: "nRF Mosuejack based datasources use a nRF USB device to detect many common wireless keyboards and mice." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Mousejack / nRF 10 | 11 | The NordicRF nRF chip is a common chip used in wireless keyboards, mice, and presentation tools, which are frequently found in non-Bluetooth wireless input devices. 12 | 13 | The Mousejack firmware developed by Bastille (https://www.mousejack.com/) runs on a number of commodity USB nRF devices (such as the Sparkfun nRF and the CrazyPA). 14 | 15 | ### Datasource - nRF Mousejack 16 | 17 | Kismet must be compiled with support for libusb to use Mousejack; you will need `libusb-1.0-dev` (or the equivalent for your distribution), and you will need to make sure that the `nRF Mousejack` option is enabled in the output from `./configure`. 18 | 19 | To use the mousejack capture, you must have a supported nRF USB device; this includes any device listed on the Bastille Mousejack site, including: 20 | - CrazyRadio PA USB dongle 21 | - SparkFun nRF24LU1+ breakout board 22 | - Logitech Unifying dongle (model C-U0007, Nordic Semiconductor based) 23 | 24 | You will need to flash your device with the Bastille Mousejack firmware; the firmware is available at [https://github.com/BastilleResearch/mousejack](https://github.com/bastilleresearch/mousejack) by following the instructions in the [Mousejack README](https://github.com/BastilleResearch/mousejack/blob/master/readme.md). 25 | 26 | #### Mousejack interfaces 27 | 28 | Mousejack datasources in Kismet can be referred to as simply `mousejack`: 29 | 30 | ```bash 31 | $ kismet -c mousejack 32 | ``` 33 | 34 | When using multiple Mousejack radios, they can be specified by their location in the USB bus; this can be detected automatically by Kismet as a supported interface in the web UI, or specified manually. To find the location on the USB bus, look at the output of the command `lsusb`: 35 | 36 | ```bash 37 | $ lsusb 38 | ... 39 | Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub 40 | Bus 003 Device 008: ID 1915:0102 Nordic Semiconductor ASA 41 | Bus 003 Device 010: ID 1915:0102 Nordic Semiconductor ASA 42 | ... 43 | ``` 44 | 45 | In this instance the first device is on `bus 003` and `device 008` and the second device is on `bus 003` and `device 010`; we can specify this specific first device in Kismet by using: 46 | 47 | ```bash 48 | $ kismet -c mousejack-3-8 49 | ``` 50 | 51 | #### Channel Hopping 52 | 53 | The nRF protocol as used by Mousejack covers 82 channels, each 1MHz wide. 54 | 55 | To cover this spectrum rapidly, it is recommended that you increase the hop rate for nRF interfaces: 56 | 57 | ```bash 58 | $ kismet -c mousejack-3-8:channel_hoprate=100/sec 59 | ``` 60 | 61 | This can also be specified in the `kismet.conf` or `kismet_site.conf` config files: 62 | 63 | ``` 64 | source=mousejack:name=nRF,channel_hoprate=100/sec 65 | ``` 66 | 67 | 68 | -------------------------------------------------------------------------------- /readme/085-server_announcing.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Server Announcements" 3 | permalink: /docs/readme/server_announcements/ 4 | excerpt: "Automatic server discovery via announcement" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Server announcements 10 | 11 | *(Added 2020-08)* 12 | 13 | Kismet supports automatic discovery of the server by remote capture sources via server announcements. 14 | 15 | This is *disabled* by default. 16 | 17 | If configured to, Kismet will announce itself via a UDP broadcast packet on UDP port 2501. This packet contains the server UUID, name, timestamp, and web and remote capture ports. 18 | 19 | Remote capture tools can use the `--autodetect` option to find the first advertising Kismet server on the local network, or the `--autodetect [uuid]` option to wait for a broadcast from a specific server UUID. 20 | 21 | Typically this would be used when building a local network of remote capture devices, where the server IP may not be known, may change, or simply for convenience - for instance using a dedicated network for capture nodes throughout a building, or using an embedded device which serves DHCP to a laptop running Kismet. 22 | 23 | ### Configuration options 24 | 25 | Server announcement is controlled by the `server_announce` options: 26 | 27 | * `server_announce=true|false` 28 | 29 | Enable the announcement subsystem. If not enabled, no announcements will be sent. 30 | 31 | * `server_announce_address=[ip]` 32 | 33 | Limit the announcements to a specific interface, as controlled by IP. By default this is `0.0.0.0`, or all interfaces, and typically this would be the desired configuration. 34 | 35 | * `server_announce_port=2501` 36 | 37 | Configure the port server announcements are sent to. Generally there is no reason to change this, and changing it will prevent other devices from finding it with the default configurations. 38 | 39 | 40 | -------------------------------------------------------------------------------- /readme/110-gps.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "GPS" 3 | permalink: /docs/readme/gps/ 4 | excerpt: "Kismet can use serial, network, and USB GPS receivers to track the location where signals are seen." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## GPS 10 | Kismet can integrate with a GPS device to provide geolocation coordinates for devices. 11 | 12 | GPS data is included in the log files, in PPI pcap files, and exported over the REST interface. 13 | ​ 14 | Kismet can not use GPS to determine the absolute location of the device; it can only use it to determine the location of the receiver. The location estimate of a device can be improved by circling the suspected location. 15 | ​ 16 | In addition to logging GPS data on a per-packet basis, Kismet maintains a running average of device locations which are exported as the average location in the Kismet UI and in device summaries. Because the running average can be heavily influenced by the sensor's position, this running average may not be very accurate. 17 | 18 | Multiple GPS devices can be defined at once, however only the highest priority active device is used. 19 | ​ 20 | GPS is configured via the `gps=` configuration option. GPS options are passed on the configuration line: 21 | ``` 22 | gps=type:option1=val1,option2=val2 23 | ``` 24 | 25 | ### Supported GPS types 26 | * serial (High priority) 27 | Locally-connected serial NMEA GPS device. This supports most USB and Bluetooth (rfcomm/spp) connected GPS devices. This does not support the few GPS devices which output proprietary binary 28 | 29 | Options: 30 | * `name=foo` 31 | Arbitrary name to identify this GPS 32 | * `device=path/to/device` 33 | Path to the serial device. The user Kismet is running as must have read access to this device. 34 | * `reconnect=true | false` 35 | Automatically attempt to re-open the serial port if there is a problem or the GPS is not connected. 36 | * `baud=rate` 37 | Specify a non-standard baud rate for the serial port. Most GPS devices operate at 4800, which Kismet uses by default. 38 | 39 | Example: 40 | ``` 41 | gps=serial:device=/dev/ttyACM0,reconnect=true,name=LaptopSerial 42 | ``` 43 | 44 | * tcp (High priority) 45 | Network-connected raw NMEA stream. Typically this is served by a smartphone app like "BlueNMEA" on Android or "NMEA GPS" on iPhone. For GPSD-based network GPS connections, use the "gpsd" GPS in Kismet. 46 | 47 | Options: 48 | * `name=foo` 49 | Arbitrary name to identify this GPS 50 | * `host=ip-or-name` 51 | IP or hostname of the server running the NMEA TCP server 52 | * `port=port number` 53 | Port number the NMEA server is listening on 54 | * `reconnect=true | false` 55 | Automatically attempt to re-open the serial port if there is a problem or the GPS is not connected. 56 | 57 | Example: 58 | ``` 59 | gps=tcp:host=10.10.100.100,port=3999 60 | ``` 61 | 62 | * gpsd (High priority) 63 | A GPSD server. GPSD (http://www.catb.org/gpsd/) parses GPS data from multiple GPS vendors (including proprietary binary) and makes it available over a standard TCP/IP connection. 64 | 65 | There are multiple GPSD versions with various levels of support and incompatible protocols. Kismet supports the older-style GPSD text protocol as well as the new GPSD3 JSON protocol. 66 | 67 | Options: 68 | * `name=foo` 69 | Arbitrary name to identify this GPS 70 | * `host=ip-or-name` 71 | IP or hostname of the server running the GPSD server 72 | * `port=port number` 73 | Port number the GPSD server is listening on; GPSD listens on port 2947 by default. 74 | * `reconnect=true | false` 75 | Automatically attempt to re-open the serial port if there is a problem or the GPS is not connected. 76 | 77 | Example: 78 | ``` 79 | gps=gpsd:host=localhost,port=2947,reconnect=true 80 | ``` 81 | 82 | * web (Medium priority) 83 | A web-based client with a modern web browser and location hardware (such as a phone) can supply their GPS location. This is only available to logged-in users on the Kismet web UI, but can turn a generic phone and web browser into a location source. 84 | 85 | Typically browsers cannot supply speed or other options, and the precision of this GPS source will be reduced because it may not be updated as frequently as a locally-connected GPS. 86 | 87 | Options: 88 | * `name=foo` 89 | Arbitrary name to identify this GPS 90 | 91 | * virtual (lowest priority) 92 | A virtual GPS always reports a static location. The virtual GPS injects location information on a stationary sensor or drone. 93 | 94 | Options: 95 | * `name=foo` 96 | Arbitrary name to identify this GPS 97 | * `lat=coordinate` 98 | Latitude coordinate. 99 | * `lon=coordinate` 100 | Longitude coordinate. 101 | * `alt=altitude` 102 | Altitude, in meters. 103 | 104 | Example: 105 | ``` 106 | gps=virtual:lat=123.4566,lon=40.002,alt=23.45 107 | ``` 108 | -------------------------------------------------------------------------------- /readme/150-siem.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Prelude SIEM" 3 | permalink: /docs/readme/integration_prelude/ 4 | excerpt: "Integration with the Prelude SIEM" 5 | docgroup: "readme" 6 | --- 7 | 8 | ## SIEM support 9 | 10 | Kismet is natively compatible with the Prelude SIEM event management system (https://www.prelude-siem.org) and can send Kismet alerts to Prelude. 11 | 12 | To enable communication with a Prelude SIEM sensor, support must be enabled at compile time by adding --enable-prelude to any other options passed to the configure script: 13 | ```bash 14 | $ ./configure --enable-prelude 15 | ``` 16 | -------------------------------------------------------------------------------- /readme/160-logs_wigle.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismet and Wigle" 3 | permalink: /docs/readme/wigle/ 4 | excerpt: "Kismetdb logs can be easily exported to the wigle CSV format for uploading." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | This tool is available as part of Kismet when built from source, or in the kismet-logtools package, as of `2019-02`. 10 | 11 | ## Wigle 12 | [Wigle](https://www.wigle.net) is a world-wide wardriving database which tracks wireless networks and their locations. 13 | 14 | Contributions to Wigle come from the community. 15 | 16 | You can contribute to Wigle by converting your logs to the Wigle CSV format, using the `kismetdb_to_wiglecsv` tool. 17 | 18 | ## Converting 19 | 20 | The simplest way to convert a kismetdb log to a wiglecsv is to simply run the conversion tool: 21 | 22 | ```bash 23 | $ kismetdb_to_wiglecsv --in some-kismet-log-file.kismet --out some-wigle-file.csv 24 | ``` 25 | 26 | ## Conversion options 27 | 28 | Converting a kismetdb log can take a lot of space and time, because each packet is examined and the coordinates written to the CSV file. This can be sped up with various options to the `kismetdb_to_wiglecsv` tool: 29 | 30 | * `--verbose` 31 | Add more status output to the console while `kismetdb_to_wiglecsv` runs. 32 | 33 | * `--skip-clean` 34 | By default, `kismetdb_to_wiglecsv` runs a SQL Vacuum command to optimize the database and clean up any journal files. Skipping this process will save time on larger captures. 35 | 36 | * `--rate-limit [rate]` 37 | Limit the export rate to `[rate]` seconds per device; an appropriate rate limit would depend on general speed you traveled during the capture. 38 | 39 | Even limiting to 1 second between updates can significantly reduce the size of the wiglecsv file. 40 | 41 | * `--cache-limit [limit]` 42 | `kismetdb_to_wiglecsv` will cache device information; by default, it will cache 1000 devices at a time. If you have a very large number of devices, and a lot of RAM, increasing this may make the conversion run faster. 43 | 44 | ## Uploading to Wigle 45 | Once your log is converted, you can upload it to [Wigle](https://www.wigle.net) by creating an account there and choosing the file from your computer. 46 | 47 | -------------------------------------------------------------------------------- /readme/161-logs_json.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismetdb to JSON" 3 | permalink: /docs/readme/kismetdb_devices_json/ 4 | excerpt: "Kismetdb logs can be exported to JSON records describing all seen devices, making it easy to process capture history." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | This tool is available as part of Kismet when built from source, or in the kismet-logtools package, as of `2019-02`. 10 | 11 | ## Device JSON 12 | Kismet stores devices it has seen in the [kismetdb log file](/docs/readme/logging/) as JSON dumps containing *everything* Kismet knows about a device. 13 | 14 | Extracting these devices can be done simply using the `kismetdb_dump_devices` tool: 15 | 16 | ```bash 17 | $ kismetdb_dump_devices --in some-kismet-file.kismet --out some-json-file.json 18 | ``` 19 | 20 | ## Export options 21 | There are several optional parameters you can use when exporting a JSON file: 22 | 23 | * `--verbose` 24 | Add more status output to the console while `kismetdb_dump_devices` runs. 25 | 26 | * `--force` 27 | By default, `kismetdb_dump_devices` will not overwrite the target file if it exists already. `--force` will cause it to clobber the destination. 28 | 29 | * `--skip-clean` 30 | By default, `kismetdb_dump_devices` runs a SQL Vacuum command to optimize the database and clean up any journal files. Skipping this process will save time on larger captures. 31 | 32 | * `--json-path` 33 | Reformat field names to be compatible with JSON path searching and ELK by rewriting all '.' to '_'; For example, `kismet.base.key` becomes `kismet_base_key`. This is turned on automatically when ELK mode is enabled. 34 | 35 | * `--ekjson` 36 | Export as an `ekjson` format; Instead of exporting a JSON array of the devices, instead export each device as an object on a single line. While not technically valid JSON, this format can be used to stream processing or inserting into other tools (such as ELK), and can be processed line-by-line with far fewer resources than a single array of all options. This will automatically enable JSON path mode. 37 | 38 | ## Streaming via `stdout` 39 | 40 | Like many other command line tools, specifying `-` as the output file will cause `kismetdb_dump_devices` to stream the output to the console, making it simple to pipe it to other tools: 41 | 42 | ```bash 43 | $ kismetdb_dump_devices --in some-kismetdb.kismet --out - | python -mjson.tool 44 | ``` 45 | 46 | -------------------------------------------------------------------------------- /readme/162-logs_strip_packets.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Stripping Kismetdb packet data" 3 | permalink: /docs/readme/kismetdb_strip_packets/ 4 | excerpt: "Kismetdb logs typically contain packet data; sometimes you may wish to strip the packet contents while keeping the device records." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | This tool is available as part of Kismet when built from source, or in the kismet-logtools package, as of `2019-02`. 10 | 11 | ## Packet data 12 | Kismet stores packets as binary data in the [kismetdb log file](/docs/readme/logging). 13 | 14 | Packet data can be invaluable for processing log files - but it can also take up space, and reveal sensitive information. Before sharing a packet log (for instance with future sites which accept kismetdb logs directly), you should strip the packet content. 15 | 16 | The `kismetdb_strip_packets` tool will retain all metadata - MAC addresses, signal, and location - but will erase the contents of the packets. 17 | 18 | ```bash 19 | $ kismetdb_strip_packets --in some-kismet-file.kismet --out some-other-file.kismet 20 | ``` 21 | 22 | ## Export options 23 | There are several optional parameters you can use when exporting a JSON file: 24 | 25 | * `--verbose` 26 | Add more status output to the console while `kismetdb_strip_packets` runs. 27 | 28 | * `--force` 29 | By default, `kismetdb_strip_packets` will not overwrite the target file if it exists already. `--force` will cause it to clobber the destination. 30 | 31 | * `--skip-clean` 32 | By default, `kismetdb_strip_packets` runs a SQL Vacuum command to optimize the database and clean up any journal files. Skipping this process will save time on larger captures. 33 | 34 | -------------------------------------------------------------------------------- /readme/163-logs_to_pcap.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismetdb to PCAP" 3 | permalink: /docs/readme/kismetdb_to_pcap/ 4 | excerpt: "Kismetdb logs can be easily converted to pcap format" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | ## Packet data 10 | Kismet stores packets as binary data in the [kismetdb log file](/docs/readme/logging). 11 | 12 | Most tools like [Wireshark](https://www.wireshark.org), [tcpdump](https://www.tcpdump.org), [Aircrack-NG](https://www.aircrack-ng.org), and many more, use the PCAP format, or the more modern variant, the PCAP-NG format. 13 | 14 | The PCAP-NG format allows for mixing different types of data (for instance, Wi-Fi and Bluetooth) into one logfile, and preserves which capture source it was received on, but isn't well supported by all tools (Wireshark and tshark offer excellent support, however). 15 | 16 | ## Converting packets with `kismetdb_to_pcap` (Added 2020-06) 17 | 18 | Installed automatically (from source) or as part of the kismet-logtools package (if installing from packages), `kismetdb_to_pcap` converts the Kismet logs to standard PCAP and PCAP-NG. 19 | 20 | ### Basic converting 21 | 22 | ```bash 23 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcapng 24 | ``` 25 | 26 | This convert the log to a standard pcapng logfile. This file contains the most information and is most useful in tools like Wireshark. 27 | 28 | If you have only one type of data - for instance, Wi-Fi packets captured from a single interface - this file will be usable with any tool which uses libpcap (such as aircrack, tcpdump, and almost all other tools.) 29 | 30 | ### Legacy PCAP 31 | 32 | `kismetdb_to_pcap` can log to legacy PCAP files as well: 33 | 34 | ```bash 35 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcap --old-pcap 36 | ``` 37 | 38 | Legacy PCAP files are limited to one DLT, or link type; the link type is the type of packet, for instance raw 802.11, radiotap signal headers, Bluetooth, and so on. 39 | 40 | Legacy PCAP files have no concept of interfaces or data sources, so if you have multiple datasources in Kismet, all the packets will be available, but it will be impossible to see what source originally captured each packet, unless you split by datasource (more on this in the next section). 41 | 42 | If your kismetdb log has more than one link type, you can specify which one will be included in the legacy pcap using the `--dlt` option: 43 | 44 | ```bash 45 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcap --old-pcap --dlt 127 46 | ``` 47 | 48 | To see what linktypes are included in your kismetdb log, use the `--list-datasources` option (see the next section for more). 49 | 50 | ### Listing and selecting datasources 51 | 52 | `kismetdb_to_pcap` can list the datasources and what link types each has captured: 53 | 54 | ```bash 55 | $ kismetdb_to_pcap --in some-kismet-log.kismet --list-datasources 56 | * Found KismetDB version 6 57 | * Collecting info about datasources... 58 | Datasource #0 (5FE308BD-0000-0000-0000-00C0CAA6846C xenon-mt2 wlx00c0caa6846c) 766980 packets 59 | DLT 127: IEEE802_11_RADIO 802.11 plus radiotap header 60 | Datasource #1 (5FE308BD-0000-0000-0000-00C0CAA68473 xenon-mt1 wlx00c0caa68473) 704950 packets 61 | DLT 127: IEEE802_11_RADIO 802.11 plus radiotap header 62 | Datasource #2 (5FE308BD-0000-0000-0000-00C0CAA68471 xenon-mt0 wlx00c0caa68471) 3656794 packets 63 | DLT 127: IEEE802_11_RADIO 802.11 plus radiotap header 64 | Datasource #3 (689C0913-0000-0000-0000-0000865F0805 rtladsb-0 rtladsb-0) 0 packets 65 | No packets seen by this datasource 66 | Datasource #4 (5FE308BD-0000-0000-0000-9CEFD5FDD05C xenon-rt28 wlx9cefd5fdd05c) 0 packets 67 | No packets seen by this datasource 68 | ``` 69 | 70 | Each datasource has a unique identifier, or UUID. Because multiple datasources could have the same interface (for example when using remote capture), datasources must be referred to by UUID. 71 | 72 | Logs can be extracted for one or more datasources: 73 | 74 | ```bash 75 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcap --old-pcap --datasource 5FE308BD-0000-0000-0000-00C0CAA6846C --datasource 5FE308BD-0000-0000-0000-00C0CAA68473 76 | ``` 77 | 78 | would generate a legacy PCAP log with only the first and second interfaces. 79 | 80 | 81 | ### Splitting logs 82 | 83 | If you have multiple datasources and want to generate a log file for each, or extremely large log files and want to split the logs by packet count or by log size, `kismetdb_to_pcap` can do that, as well: 84 | 85 | ```bash 86 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcap --old-pcap --split-datasources 87 | ``` 88 | 89 | will make a pcap for each datasource named `some-kismet-log.kismet-[uuid]`. 90 | 91 | The `--split-packets [#]` and `--split-size [kb]` options allow splitting packets by count or by total packet size in Kb: 92 | 93 | ```bash 94 | $ kismetdb_to_pcap --in some-kismet-log.kismet --out some-pcap-log.pcap --old-pcap --split-packets 10000 95 | ``` 96 | 97 | will make a pcap every 10000 packets, named `some-pcap-log.pcap-[XXXXXX]`. 98 | 99 | The `--split-datasources` option can be combined with the `--split-packets` or the `--split-size` options. 100 | 101 | 102 | ### More info 103 | 104 | More information is available via the `--help` option: 105 | 106 | ```bash 107 | $ kismetdb_to_pcap --help 108 | Convert packet data from KismetDB logs to standard pcap or pcapng logs for use in 109 | tools like Wireshark and tcpdump 110 | usage: ./log_tools/kismetdb_to_pcap [OPTION] 111 | -i, --in [filename] Input kismetdb file 112 | -o, --out [filename] Output file name 113 | -f, --force Overwrite any existing output files 114 | -v, --verbose Verbose output 115 | -s, --skip-clean Don't clean (sql vacuum) input database 116 | --old-pcap Create a traditional pcap file 117 | Traditional PCAP files cannot have multiple link types. 118 | --dlt [linktype #] Limit pcap to a single DLT (link type); necessary when 119 | generating older traditional pcap instead of pcapng. 120 | --list-datasources List datasources in kismetdb; do not create a pcap file 121 | --datasource [uuid] Include packets from this datasource. Multiple datasource 122 | arguments can be given to include multiple datasources. 123 | --split-datasource Split output into multiple files, with each file containing 124 | packets from a single datasource. 125 | --split-packets [num] Split output into multiple files, with each file containing 126 | at most [num] packets 127 | --split-size [size-in-kb] Split output into multiple files, with each file containing 128 | at most [kb] bytes 129 | ``` 130 | 131 | -------------------------------------------------------------------------------- /readme/164-logs_statistics.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismetdb Statistics" 3 | permalink: /docs/readme/kismetdb_statistics/ 4 | excerpt: "Quick summarization of kismetdb logs, with optional JSON output for scripting an index of captured log data." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | This tool is available as part of Kismet when built from source, or in the kismet-logtools package, as of `2019-04`. 10 | 11 | ## Statistics / summary 12 | 13 | The kismetdb stores the packets, interfaces, devices, and other data about a Kismet session. The `kismetdb_statistics` tool is an easy interface to analyze a capture and return information about it such as time, device counts, location coverage, etc. 14 | 15 | ```bash 16 | $ kismetdb_statistics --in some-kismet-file.kismet 17 | ``` 18 | 19 | ### Example output 20 | ``` 21 | KismetDB version: 5 22 | 23 | Packets: 447 24 | Non-packet data: 8 25 | 26 | Devices: 133 27 | Devices seen between: 2019-04-02 17:10:05 (1554239405) to 2019-04-02 17:20:46 (1554240046) 28 | 2 datasources 29 | carnuc-rtl433 rtl433-0 5E600813-0000-0000-0000-00005DBB0805 rtl433 30 | Hardware: Generic RTL2832U OEM 31 | Packets: 8 32 | carnuc-mediatek wlx000e8e5c8866 5FE308BD-0000-0000-0000-000E8E5C8866 linuxwifi 33 | Hardware: mt76x2u 34 | Packets: 424 35 | Hop rate: 5.000000/second 36 | Hop channels: 1, 1HT40+, 2, 3, 4, 5, 6, 6HT40-, 6HT40+, 7, 8, 9, 10, 11, 11HT40-, 12, 13, 14, 36, 36HT40+, 36VHT80, 40, 40HT40-, 44, 44HT40+, 48, 48HT40-, 52, 52HT40+, 52VHT80, 56, 56HT40-, 60, 60HT40+, 64, 64HT40-, 100, 100HT40+, 100VHT80, 104, 104HT40-, 108, 108HT40+, 112, 112HT40-, 116, 116HT40+, 116VHT80, 120, 120HT40-, 124, 124HT40+, 128, 128HT40-, 132, 132HT40+, 136, 136HT40-, 140, 140HT40-, 149, 149HT40+, 149VHT80, 153, 153HT40-, 157, 157HT40+, 161, 161HT40-, 165, 165HT40- 37 | 38 | Bounding location: 48.000000,-70.000000 49.000000,-75.000000 (~11.006206 Km) 39 | Packets with location: 447 40 | Data with location: 8 41 | ``` 42 | 43 | ## Outputting to JSON 44 | `kismetdb_statistics` can also output a JSON record; this can be used to index log files programmatically based on log attributes. 45 | 46 | ```bash 47 | $ kismetdb_statistics --in some_file.kismet --json 48 | ``` 49 | 50 | ### Example output 51 | ```json 52 | { 53 | "data_packets": 8, 54 | "datasources": [ 55 | { 56 | "definition": "rtl433-0:name=carnuc-rtl433", 57 | "hardware": "Generic RTL2832U OEM", 58 | "interface": "rtl433-0", 59 | "name": "carnuc-rtl433", 60 | "packets": 8, 61 | "type": "rtl433", 62 | "uuid": "5E600813-0000-0000-0000-00005DBB0805" 63 | }, 64 | { 65 | "definition": "wlx000e8e5c8866:name=carnuc-mediatek", 66 | "hardware": "mt76x2u", 67 | "hop_channels": [ 68 | "1", 69 | "1HT40+", 70 | "2", 71 | "3", 72 | "4", 73 | "5", 74 | "6", 75 | "6HT40-", 76 | "6HT40+", 77 | "7", 78 | "8", 79 | "9", 80 | "10", 81 | "11", 82 | "11HT40-", 83 | "12", 84 | "13", 85 | "14", 86 | "36", 87 | "36HT40+", 88 | "36VHT80", 89 | "40", 90 | "40HT40-", 91 | "44", 92 | "44HT40+", 93 | ], 94 | "hop_rate": 5, 95 | "interface": "wlx000e8e5c8866", 96 | "name": "carnuc-mediatek", 97 | "packets": 424, 98 | "type": "linuxwifi", 99 | "uuid": "5FE308BD-0000-0000-0000-000E8E5C8866" 100 | } 101 | ], 102 | "device_max_time": 1554240046, 103 | "device_min_time": 1554239405, 104 | "devices": 133, 105 | "diag_distance_km": 11.00620557382399, 106 | "file": "/home/dragorn/wavehack/carnuc-20190402-17-10-03-1.kismet", 107 | "kismetdb_version": 5, 108 | "max_lat": 40.000000000, 109 | "max_lon": -70.000000000, 110 | "min_lat": 45.000000000, 111 | "min_lon": -75.000000000, 112 | "packets": 447 113 | } 114 | ``` 115 | 116 | 117 | ## Options 118 | There are several optional parameters you can use: 119 | 120 | * `--skip-clean` 121 | By default, `kismetdb_strip_packets` runs a SQL Vacuum command to optimize the database and clean up any journal files. Skipping this process will save time on larger captures. 122 | 123 | * `--json` 124 | Output as a JSON file; useful when using the `kismetdb_statistics` tool to populate an index of log files or similar. 125 | -------------------------------------------------------------------------------- /readme/165-logs_kml.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismet and KML" 3 | permalink: /docs/readme/kml/ 4 | excerpt: "Kismetdb logs can be easily exported to KML for use with Google Earth" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | This tool is available as part of Kismet when built from source, or in the kismet-logtools package, as of `2019-07-git`. 10 | 11 | ## KML 12 | KML is an XML-based markup language for use with Google Earth. 13 | 14 | ## Converting 15 | 16 | The simplest way to convert a kismetdb log to a KML is to simply run the conversion tool: 17 | 18 | ```bash 19 | $ kismetdb_to_kml --in some-kismet-log-file.kismet --out some-kml-file.kml 20 | ``` 21 | 22 | ## Conversion options 23 | 24 | * `--verbose` 25 | 26 | Add more status output to the console while `kismetdb_to_kml` runs. 27 | 28 | * `--skip-clean` 29 | 30 | By default, `kismetdb_to_kml` runs a SQL Vacuum command to optimize the database and clean up any journal files. Skipping this process will save time on larger captures. 31 | 32 | * `--basic-location` 33 | 34 | By default, `kismetdb_to_kml` computes a final average across all the packets seen; this can be more precise than the running average Kismet computes. If packets were not logged, or to save time and processing, passing `--basic-location` will use the average location computed runtime, instead. 35 | 36 | -------------------------------------------------------------------------------- /readme/180-wardrive_mode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Kismet Wardriving Mode" 3 | permalink: /docs/readme/wardriving/ 4 | excerpt: "Simplified wardriving mode for smaller platforms" 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | The wardriving mode configuration overlay (and code to support it) was added to Kismet in `2022-01-git` and subsequent releases. 10 | 11 | ## Wardriving mode 12 | 13 | Kismet is already equipped for what most would consider to be wardriving out of the box: With a GPS and one (or more) Wi-Fi cards, Kismet will generate logs suitable for uploading to Wigle or generating your own maps and logs. 14 | 15 | Many people however want to run Kismet on what would typically be considered light-weight or even underpowered hardware, which presents challenges in high-density areas (or even lower density areas, depending how under-powered the hardware is). 16 | 17 | Kismet provides a configuration overlay file which preconfigures Kismet to optimize it for basic wardriving - this turns off most logging and data retention, disables processing most packets as much as possible, and configures the radios for optimized AP detection. All this comes at the cost of normal functionality - in wardrive mode, Kismet won't track non-access-point Wi-Fi devices, perform most IDS functionality, log data packets, or retain handshakes. What it *will* do is function much better for the specific goal of mapping access points and Bluetooth devices. 18 | 19 | ## Wigle logs 20 | 21 | Kismet can now export directly to [Wigle](https://wigle.net) compatible CSV logs. These contain access points and bluetooth devices. 22 | 23 | Because Wigle is designed to collect locational information, Kismet will only write to the log when a GPS location is present. 24 | 25 | ## It's just a config overlay 26 | 27 | Remember - wardriving mode is *optional*, and it's *just a configuration overlay*. If the example overlay doesn't suit your needs, just copy it and change the config! 28 | 29 | ## Using wardriving mode 30 | 31 | To use wardriving mode, just launch Kismet with the `--override` option (in addition to any other command line options you pass), for instance: 32 | 33 | ```bash 34 | $ kismet -t some_wardrive --override wardrive 35 | ``` 36 | 37 | You'll receive an alert that wardriving mode is active and that logging is greatly reduced, and Kismet will automatically be optimized for pure AP collection. 38 | 39 | ## Digging into the wardriving mode config 40 | 41 | What does wardriving mode change? You can see all the options in the `kismet_wardrive.conf` config file: 42 | 43 | * Raise an alert 44 | 45 | Kismet will fire an extra alert to make sure it's obvious wardriving mode is engaged and not all data will be logged. 46 | 47 | ``` 48 | load_alert=WARDRIVING:Kismet is in survey/wardriving mode. This turns off tracking non-AP devices and most packet logging. 49 | ``` 50 | 51 | * Enable wiglecsv logging 52 | 53 | Kismet can log directly to wiglecsv format; this adds it to whatever other log types are already configured. 54 | 55 | ``` 56 | # Turn on wiglecsv format 57 | log_types+=wiglecsv 58 | ``` 59 | 60 | * Turn off HT Wi-Fi channels 61 | 62 | Access point advertisements only happen on the primary Wi-Fi channels; there's no need to tune to HT20, HT40, VHT80, or VHT160 channels. By eliminating them, we increase the effective channel coverage by hopping through the list faster, meaning we're less likely to miss APs while in motion. 63 | 64 | The options are appended to any 802.11 datasource, local or remote, which doesn't have an explicit option already set. Specific sources could be left on VHT channels by adding `ht_channels=true,vht_channels=true,default_ht20=true,expand_ht20=true` to those datasource `source=` defintiions. 65 | 66 | ``` 67 | # Turn off HT20, HT40, and VHT options on wifi datasources (unless they explicitly set them) 68 | dot11_datasource_opt=ht_channels,false 69 | dot11_datasource_opt=vht_channels,false 70 | dot11_datasource_opt=default_ht20,false 71 | dot11_datasource_opt=expand_ht20,false 72 | ``` 73 | 74 | * Turn on advanced filtering 75 | 76 | *Added in 2022-06* 77 | 78 | Enable a kernel BPF (packet filter language) filter that only passes 802.11 management and EAPOL (WPA handshake) frames. This greatly reduces the number of packets Kismet must process. 79 | 80 | ``` 81 | dot11_datasource_opt=filter_mgmt 82 | ``` 83 | 84 | * Tune 802.11 tracking 85 | 86 | Kismet normally tracks all device it sees, keeps fingerprints, optionally keeps IE tags for display, and keeps handshakes. All of this takes memory, so we turn it off. 87 | 88 | ``` 89 | dot11_ap_only_survey=true 90 | dot11_fingerprint_devices=false 91 | dot11_keep_ietags=false 92 | dot11_keep_eapol=false 93 | ``` 94 | 95 | * Turn off some other logging 96 | 97 | The kismetdb log can contain channel usage over time, datasource rates over time, and other info - we don't care about that for wardriving, turn it off. This saves both disk space and IO time to slower disks, like microsd cards. 98 | 99 | ``` 100 | kis_log_channel_history=false 101 | kis_log_datasources=false 102 | ``` 103 | 104 | 105 | 106 | -------------------------------------------------------------------------------- /readme/200-libraries.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Included libraries" 3 | permalink: /docs/readme/libraries/ 4 | excerpt: "Kismet wouldn't be possible without other open source projects and includes several open source libraries." 5 | docgroup: "readme" 6 | --- 7 | 8 | ## Integrated libraries 9 | 10 | Kismet uses several libraries which are built as part of the Kismet source code; without the open-source community this wouldn't be possible. 11 | 12 | * [fmtlib](https://github.com/fmtlib/fmt): C++ string formatting for faster message generation with fewer temporary variables. 13 | * [jsoncpp](http://jsoncpp.sourceforge.net/): JSON parser 14 | * [kaitai](https://kaitai.io): Binary parser generator and stream library 15 | * [microhttpd](https://www.gnu.org/software/libmicrohttpd/): Webserver 16 | * [nlohmann json](https://github.com/nlohmann/json): JSON sanitization 17 | * [sha1](https://github.com/vog/sha1): Simple SHA1 implementation 18 | * [radiotap](http://radiotap.org): Radiotap header definitions 19 | * [xxhash32](https://github.com/Cyan4973/xxHash): Fast 32bit hashing algorithm 20 | -------------------------------------------------------------------------------- /readme/_base.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: ".." 3 | permalink: /docs/readme/xyz/ 4 | excerpt: ".." 5 | docgroup: "readme" 6 | toc: true 7 | --- 8 | 9 | --------------------------------------------------------------------------------