Kismet 2018-08-BETA1

https://www.kismetwireless.net

MAJOR KISMET UPDATE

Welcome to the new, MAJOR rewrite of Kismet! This version changes almost everything, hopefully for the better, including:

Please remember that as a pre-release, there is still some 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.

Setting up the new Kismet is generally simpler than the older versions, keep reading for more information!

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!

 


Kismet 2018-08-BETA1MAJOR KISMET UPDATEQuick SetupDebugging KismetAdvanced debuggingUpgrading & Using Kismet Git-Master (or beta)Installing Kismet - Suid vs NormalWhy does Kismet need root?Starting KismetConfiguring KismetConfiguration FormatConfiguration Override Files - kismet_site.confKismet Data SourcesNaming and describing data sourcesSetting source IDsMultiple Kismet DatasourcesWi-FiWi-Fi ChannelsDatasource: Linux Wi-FiSupported HardwareLinux Wi-Fi Source ParametersSpecial Linux Wi-Fi DriversData source: OSX WifiOSX Wi-fi ParametersTuning Wi-Fi Packet CaptureBluetoothDatasource: Linux BluetoothExample sourceSupported HardwareService ScanningBluetooth Source ParametersReplaying dataDatasource - PcapfilePcapfile OptionsSDRDatasource - SDR RTL433Remote Packet CaptureAny-to-AnyControlling access to remote captureAdditional remote capture optionsCompiling Only the Capture ToolsKismet WebserverGPSSupported GPS typesKismet Memory and Processor TuningSIEM supportIntegrated libraries

Quick Setup

Kismet has many configuration knobs and options; but for the quickest way to get the basics working:

  1. Uninstall any existing Kismet installs. If you installed Kismet using a package from your distribution, uninstall it the same way; if you compiled it yourself, be sure to remove it

  2. Install dependencies. Kismet needs a number of libraries and development headers to compile; these should be available in nearly all distributions.

    Ubuntu/Debian/Kali/Mint

    On some older versions, libprotobuf-c-dev may be called libprotobuf-c0-dev.For the Python add-ons, you will also need:

    You can also use the pip equivalents of the python libraries, so long as they're installed in a location your normal Python interpreter can find them.

    For rtlsdr rtl_433 support, you will also need:

    as well as the rtl_433 tool from https://github.com/merbanan/rtl_433 if it is not otherwise provided by your distribution.

  3. Clone Kismet from git. If you haven't cloned Kismet before:

    If you have a Kismet repo already:

  4. Run configure. This will find all the specifics about your system and prepare Kismet for compiling. If you have any missing dependencies or incompatible library versions, they will show up here.

    Pay attention to the summary at the end and look out for any warnings! The summary will show key features and raise warnings for missing dependencies which will drastically affect the compiled Kismet.

  5. Compile Kismet.

    You can accelerate the process by adding -j #, depending on how many CPUs you have. For instance on a quad-core system:

    C++ uses quite a bit of RAM to compile, so depending on the RAM available on your system you may need to limit the number of processes you run simultaneously.

  6. Install Kismet. Generally, you should install Kismet as suid-root; Kismet will automatically add a group and install the capture binaries accordingly.

    When installed suid-root, Kismet will launch the binaries which control the channels and interfaces with the needed privileges, but will keep the packet decoding and web interface running without root privileges.

  7. Put yourself in the Kismet group.

    This will add foouser to the Kismet group.

  8. Log out and back in. Linux does not update groups until you log in; if you have just added yourself to the Kismet group you will have to re-log in.

  9. Check that you are in the Kismet group with:

    If you are not in the kismet group, you should log out entirely, or reboot.

  10. You're now ready to run Kismet! Point it at your network interface... Different distributions (and kernel versions, and distribution versions) name interfaces differently; your interface may be wlan0 or wlan1, or it may be named something like wlp0s1, or it may be named using the MAC address of the card and look like wlx00c0ca8d7f2e.

    You can now start Kismet with something like:

    or, you can just launch Kismet and then use the new web UI to select the card you want to use, by launching it with just:

    Remember, until you add a data source, Kismet will not be capturing any packets!

    THE FIRST TIME YOU RUN KISMET, it will generate a new, random password for your web interface.

    This password can be found in the config file: ~/.kismet/kismet_httpd.conf which is in the home directory of the user starting Kismet.

    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.

You will need this password to control Kismet from the web page - without it you can still view information about devices, view channel allocations, and most other actions, but you CAN NOT control Kismet data sources, view pcaps, or perform other actions.

  1. Point your browser at http://localhost:2501

    You will be prompted to do basic configuration - Kismet has many options in the web UI which can be tweaked.

    To use all the features of the Kismet web UI, put in the password found in ~/.kismet/kismet_httpd.conf

Debugging Kismet

Kismet (especially in beta) is in a state of rapid development - this means that bad things can creep into the code. Sorry about that!

If you're interested in helping debug problems with Kismet, here's the most useful way to do so:

  1. Compile Kismet from source (per the quick start guide above)

  2. Install Kismet (typically via sudo make suidinstall)

  3. Run Kismet, FROM THE SOURCE DIRECTORY, in gdb:

    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.

  4. Tell GDB to ignore the PIPE signal

    This tells GDB not to intercept the SIGPIPE signal (which can be generated, among other times, when a data source has a problem)

  5. Configure GDB to log to a file

    This saves all the output to gdb.txt

  6. Run Kismet - in debug mode

    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:

  7. Wait for Kismet to crash

  8. Collect a backtrace

    This shows where Kismet crashed.

  9. Collect thread info

    This shows what other threads were doing, which is often critical for debugging.

  10. Collect per-thread backtraces

    This generates a dump of all the thread states

  11. 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)

Advanced debugging

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:

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.

Upgrading & Using Kismet Git-Master (or beta)

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

You can then configure, and install, the new Kismet per the quickstart guide above.

While heavy development is underway, the config file may change; generally breaking changes will be mentioned on Twitter and in the git commit logs.

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)

Installing Kismet - Suid vs Normal

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:

Nearly all packages of Kismet should support the suid-root install method as well.

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.

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.

Why does Kismet need root?

Controlling network interfaces on most systems requires root, or super-user access.

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.

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.

Starting Kismet

Kismet can be started normally from the command line, and will run in a small ncurses-based wrapper which will show the most recent server output, and a redirect to the web-based interface.

Kismet can also be started as a service; typically in this usage you should also pass --no-ncurses to prevent the ncurses wrapper from loading.

An example systemd script is in the packaging/systemd/ directory of the Kismet source.

Configuring Kismet

Kismet is primarily configured through a set of configuration text files. By default these are installed into /usr/local/etc/. The config files are broken into several smaller files for readability:

Configuration Format

Configuration files are plain text. Lines beginning with a # are comments, and are ignored.

Configuration options all take the form of: option=value

Some configuration options support repeated definitions, such as the source option which defines a Kismet datasource: source=wlan0 source=wlan1

Kismet supports importing config files. This is used by Kismet itself to split the config files into more readable versions, but can also be used for including custom options.

Configuration Override Files - kismet_site.conf

Most users installing Kismet will likely edit the configuration files directly. This file is not needed by most users, and can be ignored, however if you are configuring Kismet on multiple systems, this may be useful.

When Kismet frequently from source (for instance, testing Git) or preparing Kismet server deployments across multiple systems presents other challenges.

By default, Kismet will look for an optional override file in the default configuration directory (/usr/local/etc by default) named kismet_site.conf.

This file is specified as an OVERRIDE FILE. Any options placed in kismet_site.conf will REPLACE ANY OPTIONS OF THE SAME NAME.

This mechanism allows a site configuration to override any default config options, while not making changes to any configuration file installed by Kismet. This allows new installations of Kismet to replace the config files with impunity while preserving a custom configuration.

Typical uses of this file might include changing the http data directory, defining sources and memory options, forcing or disabling logging, and so on; a kismet_site.conf file might look like:

Kismet Data Sources

Kismet gets data (which can be packets, devices, or other information) from "data sources".

Data sources can be created several ways:

Source definitions look like:

For example to capture from a Linux Wi-Fi device on wlan1 with no special options:

To capture from a Linux Wi-Fi device on wlan1 while setting some special options, like telling it to not change channels and to capture from channel 6:

Different data sources have different options, read on for more information about the different capture sources Kismet supports.

When no options are provided for a data source, the defaults are controlled by settings in kismet.conf; these defaults are applied to all new datasources:

Naming and describing data sources

Datasources allow for annotations; these have no role in how Kismet operates, but the information is stored alongside the source definition and is available in the Kismet logs and in the web interface.

The following information can be set in a source, but is not required:

Setting source IDs

Typically Kismet generates a UUID based on attributes of the source - the interface MAC address if the datasource is linked to a physical interface, the devices position in the USB bus, or some other consistent identifier. To override the UUID generation, the uuid=... parameter can be set:

source=wlan0:name=foo,uuid=AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE

If you are assigning custom UUIDs, you must ensure that every UUID is unique. Each data source must have its own unique identifier.

Multiple Kismet Datasources

Kismet will attempt to open all the sources defined on the command line (with the -c option), or if no sources are defined on the command line, all the sources defined in the Kismet config files.
If a source has no functional type and encounters an error on startup, it will be ignored - for instance if a source is defined as:

   source=wlx4494fcf30eb3

and that device is not connected when Kismet is started, it will raise an error but will be ignored.

To force Kismet to try to open a device which could not be found at startup, you will need to provide the source type; for instance, the same source defined with the type field:

   source=wlx4494fcf30eb3:type=linuxwifi

will continually try to re-open the device.

Wi-Fi

Wi-Fi Channels

Wi-Fi channels in Kismet define both the basic channel number, and extra channel attributes such as 802.11N 40MHz channels, 802.11AC 80MHz and 160MHz channels, and non-standard half and quarter rate channels at 10MHz and 5MHz.
Kismet will auto-detect the supported channels on most Wi-Fi cards. Monitoring on HT40, VHT80, and VHT160 requires support from your card.
Channels can be defined by number or by frequency.

DefinitionInterpretation
xxBasic 20MHz channel, such as 6 or 153
xxxxBasic 20MHz frequency, such as 2412
xxHT40+40MHz 802.11n with upper secondary channel, such as 6HT40+
xxHT40-40MHz 802.11n with lower secondary channel, such as 6HT40-
xxVHT8080MHz 802.11ac channel, such as 116VHT80
xxVHT160160MHz 802.11ac channel, such as 36VHT160
xxW1010MHz half-channel, a non-standard channel type supported on some Atheros devices. This cannot be automatically detected, you must manually add it to the channel list for a source.
xxW55MHz quater-channel, a non-standard channel type supported on some Atheros devices. This cannot be automatically detected, you must manually add it to the channel list for a source.

Datasource: Linux Wi-Fi

Most likely this will be the main data source most people use when capturing with Kismet.

The Linux Wi-Fi data source handles capturing from Wi-Fi interfaces using the two most recent Linux standards: The new netlink/mac80211 standard present since approximately 2007, and the legacy ioctl-based IW extensions system present since approximately 2002.

Packet capture on Wi-Fi is accomplished via "monitor mode", a special mode where the card is told to report all packets seen, and to report them at the 802.11 link layer instead of emulating an Ethernet device.

The Linux Wi-Fi source will auto-detect supported interfaces by querying the network interface list and checking for wireless configuration APIs. It can be manually specified with type=linuxwifi:

source=wlan1:type=linuxwifi

The Linux Wi-Fi capture uses the 'kismet_cap_linux_wifi' tool, and should typically be installed suid-root: Linux requires root to manipulate the network interfaces and create new ones.

Example source definitions:

source=wlan0
source=wlan1:name=some_meaningful_name

Supported Hardware

Not all hardware and drivers support monitor mode, but the majority do. Typically any driver shipped with the Linux kernel supports monitor mode, and does so in a standard way Kismet understands. If a specific piece of hardware does not have a Linux driver yet, or does not have a standard driver with monitor mode support, Kismet will not be able to use it.

The Linux Wi-Fi source is known to support, among others:

Devices known to have issues:

Kismet generally will not work with most other out-of-kernel (drivers not shipped with Linux itself), specifically drivers such as the SerialMonkey RTL drivers used for many of the cheap, tiny cards shipped with devices like the Raspberry Pi and included in distributions like Raspbian. Some times it's possible to find other, supported drivers for the same hardware, however some cards have no working solution.

Many more devices should be supported - if yours isn't listed and works, let us know via Twitter (@kismetwireless).

Linux Wi-Fi Source Parameters

Linux Wi-Fi sources accept several options in the source definition, in addition to the common name, informational, and UUID elements:

Special Linux Wi-Fi Drivers

Some drivers require special behavior - whenever possible, Kismet will detect these drivers and "do the right thing".

Data source: OSX Wifi

Kismet can use the built-in Wi-Fi on a Mac, but ONLY the built-in Wi-Fi; Unfortunately currently there appear to be no drivers for OSX for USB devices which support monitor mode.

Kismet uses the kismet_cap_osx_corewlan_wifi tool for capturing on OSX.

OSX Wi-fi Parameters

OSX Wi-Fi sources support the standard options supported by all sources (such as name, uuid, and informational elements) as well as:

Tuning Wi-Fi Packet Capture

Kismet has a number of tuning options to handle quirks in different types packet captures. These options can be set in the kismet.conf config file to control how Kismet behaves in some situations:

Bluetooth

Bluetooth uses a frequency-hopping system with dynamic MAC addresses and other oddities - this makes sniffing it not as straightforward as capturing Wi-Fi.

Currently the only implemention of Bluetooth scanning in Kismet uses the Linux HCI layer to perform active device scans.

Support for Bluetooth capture using the Ubertooth One hardware will be forthcoming.

Datasource: Linux Bluetooth

Currently the Kismet implementation of Bluetooth discovery uses the Linux HCI layer to perform device scans to detect dicoverable Bluetooth Classic devices and BTLE devices; this is an active scan, not passive monitoring.

The Linux Bluetooth source will auto-detect supported interfaces by querying the bluetooth interface list. It can be manually specified with type=linuxbluetooth.

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.

Example source
source=hci0:name=linuxbt
Supported Hardware

For simply identifying Bluetooth (and BTLE) devices, the Linux Bluetooth datasource can use any standard Bluetooth interface supported by Linux.

This includes almost any built-in Bluetooth interface, as well as external USB interfaces such as the Sena UD100.

Service Scanning

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.

Complex service scanning and enumeration will be coming in a future revision.

Bluetooth Source Parameters

Linux Bluetooth sources support all the common configuration options such as name, information elements, and UUID.

Replaying data

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.

Kismet can replay a pcapfile for testing, debugging, demo, or reprocessing.

Datasource - Pcapfile

The Pcapfile datasource will auto-detect pcap files and paths to files:

It can be manually specified with type=pcapfile

The pcapfile capture uses the 'kismet_cap_pcapfile' tool which does not need special privileges.

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.

Pcapfile Options

In addition to the normal options supported by all sources (name, information elements, UUID, etc) the pcapfile source can also support:

SDR

SDR, or software-defined radio, uses special generic hardware to capture radio signals, and performs signal processing in software.

SDR is extremely powerful, but also often extremely brittle - configuring SDR hardware and software to work reliably can be quite difficult. Kismet is able to use external SDR tools to interface with hardware and utilize some of the power of SDR.

Datasource - SDR RTL433

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.

Kismet is able to process data from the rtl_433 tool, which can read the broadcasts of an multitude of wireless thermometer, weather, electrical, tire pressure, and other sensors.

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.

More information about the rtl-sdr is available at: https://www.rtl-sdr.com

The rtl_433 tool can be downloaded from: https://github.com/merbanan/rtl_433 or as a package in your distribution.

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.

For more information about the rtl433 support, see the README in the capture_sdr_rtl433 directory.

Remote Packet Capture

Kismet can capture from a remote source over a TCP connection.

Kismet remote packet feeds are initiated by the same tools that Kismet uses to configure a local source; for example if Kismet is running on a host on IP 192.168.1.2, to capture from a Linux Wi-Fi device on another device you would use:

Specifically, this uses the kismet_cap_linux_wifi tool, which is by default installed in /usr/local/bin/, to connect to the IP 192.168.1.2 port 3501.

The --source=... parameter is the same as you would use in a source= Kismet configuration file entry, or as -c to Kismet itself.

Source definitions of a remote capture are controlled the same way as source= definitions in the Kismet config, and can take the same options:

Any-to-Any

Kismet is designed to allow any source to function as a remote capture, and to function cross-platform. It is completely reasonable, for instance, to use an OpenWRT sensor running Linux to provide packets to a Kismet server running on OSX or Windows 10 under the WSL.

Controlling access to remote capture

For security reasons, by default Kismet only remote sensor connections from the localhost IP (127.0.0.1). To connect remote sensors, you must either:

  1. Set up a tunnel from the remote sensor to your Kismet server, for example using SSH port forwarding. This is very simple to do, and adds encryption transparently to the remote packet stream. This can be done as simply as:

    This sets up a SSH tunnel from localhost port 3501 to 192.168.1.2 port 3501. Then in a second terminal running the Kismet remote capture, using localost:3501 as the destination:

    # /usr/local/bin/kismet_cap_linux_wifi --connect localhost:3501 --source=wlan1
    

    Other, more elegant solutions exist for building the SSH tunnel, such as autossh which can be used to automatically maintain the tunnel and start it on boot.

  2. Kismet can be configured to accept connections on a specific interface, or from all IP addresses, by changing the remote_capture_listen= line in kismet.conf or kismet_site.conf as an override. To enable listening on ALL network interfaces:

    remote_capture_listen=0.0.0.0
    

    Or a single specific network interface:

    remote_capture_listen=192.168.1.2
    

    Remote capture should only be enabled on interfaces on a protected LAN.

Additional remote capture options

Kismet capture tools also support the following options:

Compiling Only the Capture Tools

Typically, you will want to compile all of Kismet. If you're doing specific remote-capture installs, however, you may wish to compile only the binaries used by Kismet to enable capture mode and pass packets to a full Kismet server.

To compile ONLY the capture tools:

Tell configure to only configure the capture tools; this will allow you to configure without installing the server dependencies such as C++, microhttpd, protobuf-C++, etc. You will still need to install dependencies such as protobuf-c, build-essentials, and similar:

Once configure has completed, compile the capture tools:

You can now copy the compiled datasources to your target.

Kismet Webserver

Kismet now integrates a webserver which serves the web-based UI and data to external clients.

THE FIRST TIME YOU RUN KISMET, it will generate a RANDOM password. This password is stored in ~/.kismet/kismet_httpd.conf which is in the home directory of the user which started Kismet.

You will need this password to log into Kismet for the first time.

The webserver is configured via the kismet_httpd.conf file. These options may be included in the base kismet.conf file, but are broken out for clarity. These options may be overridden in kismet_site.conf for pre-configured installs.

By default, Kismet does not run in SSL mode. If you provide a certificate and key file in PEM format, Kismet supports standard SSL / HTTPS. For more information on creating a SSL certificate, look at README.SSL

HTTP configuration options:

GPS

Kismet can integrate with a GPS device to provide geolocation coordinates for devices.

GPS data is included in the log files, in PPI pcap files, and exported over the REST interface.
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.
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 sensors position, this running average may not be very accurate.

Multiple GPS devices can be defined at once, however only the highest priority active device is used.
GPS is configured via the gps= configuration option. GPS options are passed on the configuration line:

gps=type:option1=val1,option2=val2

Supported GPS types

Kismet Memory and Processor Tuning

Kismet has several options which control how much memory and processing it uses. These are found in kismet_memory.conf. Generally it is not necessary to tune these values unless you are running on extremely limited hardware or have a very large number of devices (over 10,000) detected.

SIEM support

Kismet is natively compatible with the Prelude SIEM event management system (https://www.prelude-siem.org) and can send Kismet alerts to Prelude.

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:

Integrated libraries

Kismet uses several libraries which are part of the Kismet source code; Without the open source community this wouldn't be possible.