nstkismet

Name

nstkismet — NST script to administer kismet.

Synopsis

Description

The nstkismet script is used to administer Kismet in a NST distribution.

Typical usage of this script involves:

Invoke the script with --mode setup to prepare the NST system to run Kismet.
Edit the kismet_server configuration (/etc/kismet/kismet.conf) to match your hardware setup.
Start the kismet_server by invoking systemctl start kismet.service.
Use the kismet_client to see what traffic has been detected.
Stop the kismet_server by invoking systemctl stop kismet-service.service (this is optional).
Remove the Kismet setup completely by running the script with the --mode remove option.

Here is a example of using nstkismet:


[root@probe ~]# nstkismet --mode setup --source auto -v
Created package directory: /var/nst/kismet
Adding: "ncsource=wlan0"
Successfully updated the ncsource line(s) in: "/etc/kismet/kismet.conf"

***************************************************************
Kismet setup complete. Proceed as follows:

A. Edit /etc/kismet/kismet.conf

B. Bring up the server via:

     systemctl start kismet.service

   OR - start server and client via:

     (cd ~kismet && kismet)

NOTE: Step A is semi-optional as a kismet source adapter was
successfully configured.
***************************************************************
[root@probe ~]# nstkismet --mode status -v
kismet is setup under: /var/nst/kismet
[root@probe ~]# nstkismet --mode location
/var/nst/kismet[root@probe ~]# vi /etc/kismet/kismet.conf

... adjust kismet configuration - the 'ncsource' line is critical ...

[root@probe ~]# systemctl start kismet.service
[root@probe ~]# kismet_client

... look at what's going on ...

[root@probe ~]# systemctl stop kismet.service
[root@probe ~]# nstkismet --mode remove -v
Successfully removed /var/nst/kismet and the kismet user
[root@probe ~]#

Note

A web based front end to this script is available in the NST WUI.

Generating KMZ Output

If you have a GPS connected to your system, it is possible for Kismet to geolocate the systems which it detects. The raw latitude and longitude coordinates will be found in a file with the extension "gpsxml".

You can use this script to merge the information from the "netxml" file and corresponding "gpsxml" file into a single KMZ file which can be loaded into applications like Google Earth.

To produce a KMZ file, you will need to first determine the "tag" name which identifies the files. This can be done using the following command:


[root@probe ~]# ls /var/nst/kismet
Kismet-20100923-13-54-23-1.alert     Kismet-20101025-08-55-17-1.netxml
Kismet-20100923-13-54-23-1.gpsxml    Kismet-20101025-08-55-17-1.pcapdump
Kismet-20100923-13-54-23-1.nettxt    Kismet-20101025-12-12-31-1.alert
Kismet-20100923-13-54-23-1.netxml    Kismet-20101025-12-12-31-1.gpsxml
Kismet-20100923-13-54-23-1.pcapdump  Kismet-20101025-12-12-31-1.nettxt
Kismet-20101025-08-55-17-1.alert     Kismet-20101025-12-12-31-1.netxml
Kismet-20101025-08-55-17-1.gpsxml    Kismet-20101025-12-12-31-1.pcapdump
Kismet-20101025-08-55-17-1.nettxt    kismet_server.log
You have new mail in /var/spool/mail/root
[root@probe ~]#

From the output above, you can see that there are three different tags identifying each set of correpsonding files: "Kismet-20100923-13-54-23-1", "Kismet-20101025-08-55-17-1", and "Kismet-20101025-12-12-31-1". To generate a KMZ file use the following command:


[root@probe ~]# nstkismet -m kmz --tag Kismet-20100923-13-54-23-1 >| kismet.kmz
[root@probe ~]#

It's possible that the generation of the KMZ file will fail. If the KMZ generation fails, the script will exit with a return code of 1 and produce a error message on stderr. This typically occurs for one of two reasons. One, there was no GPS data available. Two, the Kismet server has not closed out the data files (only partial results are available). You can force the Kismet server to close its current files by either stopping or restarting the kismet service.

Generating MAC Lists

If you use Kismet to keep tabs on your own personal network, it can be useful to keep track of the systems connecting to your network. Using the "mac" mode, you can get a list of MACs for all the systems detected by Kismet. You can limit the output to the clients for a particular network by including the "--bssid BSSID" option.

To produce a MAC list, you will need to first determine the "tag" name associated with the "netxml" file. This can be done using the following command:


[root@probe ~]# ls /var/nst/kismet
Kismet-20100923-13-54-23-1.alert     Kismet-20101025-08-55-17-1.netxml
Kismet-20100923-13-54-23-1.gpsxml    Kismet-20101025-08-55-17-1.pcapdump
Kismet-20100923-13-54-23-1.nettxt    Kismet-20101025-12-12-31-1.alert
Kismet-20100923-13-54-23-1.netxml    Kismet-20101025-12-12-31-1.gpsxml
Kismet-20100923-13-54-23-1.pcapdump  Kismet-20101025-12-12-31-1.nettxt
Kismet-20101025-08-55-17-1.alert     Kismet-20101025-12-12-31-1.netxml
Kismet-20101025-08-55-17-1.gpsxml    Kismet-20101025-12-12-31-1.pcapdump
Kismet-20101025-08-55-17-1.nettxt    kismet_server.log
You have new mail in /var/spool/mail/root
[root@probe ~]#


[root@probe ~]# nstkismet -m mac --tag Kismet-20100923-13-54-23-1 >| current.mac.txt
[root@probe ~]#

Since only the "netxml" file is required as input, you may omit the "--tag TAG" option and direct in the file you would like to process. For example:


[root@probe ~]# nstkismet -m mac < /var/nst/kismet/Kismet-20100923-13-54-23-1.netxml >| current.mac.txt
[root@probe ~]#

Use the "--bssid BSSID" option to limit the results to a single network. For example, the following generates the MAC list for the 0E:18:32:82:94:43 network from two different Kismet "netxml" files and then compares the two to see if any new machines appeared on the network:


[root@probe ~]# bssid="0E:18:32:82:94:43"
[root@probe ~]# nstkismet -m mac --bssid $bssid --tag Kismet-20100923-13-54-23-1 >| ${bssid}.a.mac.txt
[root@probe ~]# nstkismet -m mac --bssid $bssid --tag Kismet-20101025-08-55-17-1 >| ${bssid}.b.mac.txt
[root@probe ~]# diff ${bssid}.a.mac.txt ${bssid}.b.mac.txt
[root@probe ~]#

Options

The following command line options are available:

[-m TEXT] | [--mode TEXT]: This option controls what nstkismet will do. If you specify "status" (the default), the script will exit with a 0 return code if the system is already setup. If you specify "setup" the script removes any previous Kismet set up and then sets up your NST system to run the kismet_server as a systemd service. If you specify "remove" it will remove the Kismet setup from your system. If you specify "location" it will display the location of the run time directory (according to the last setup). If you specify "kmz" it will try to generate a KMZ file which can be loaded in Google Earth (you will need to specify "--tag TAG as well). If you specify "mac" it will try to generate a sorted text file containing each MAC for the systems detected by Kismet (you will need to specify "--tag TAG" OR direct in a Kismet XML file).
[--source TEXT]: This option is used in "setup" mode. It is used to specify the initial value for the "ncsource" line in the file: "/etc/kismet.conf". You may specify a standard Kismet source in the form: "INTERFACE[:OPTION=VAL[,OPTION=VAL...]]". For example: "wlan0" and "wlan1:hop=false,channel=11" (see the Kismet README for details). In addition to specifying the full source, one may instead specify the keyword "auto" or "none". If "auto" is specified, the script will try to automatically determine what the source line should be by looking for: "/sys/class/net/*/wireless" entries. If the keyword "none" is specified then the script will NOT update the file: "/etc/conf/kismet.conf". NOTE: If this option is omitted, the script will default to the "auto" mode behavior.
[--tag TEXT]: This option is used in the "kmz" and "mac" modes. It indicates which XML file(s) will be used from the output directory (/var/nst/kismet unless -rdir DIR is specified during setup). For example, if you specify "Kismet-20100923-13-54-23-1" the files: "/var/nst/kismet/Kismet-20100923-13-54-23-1.netxml" and "/var/nst/kismet/Kismet-20100923-13-54-23-1.netxml" would be used.
[--bssid TEXT]: This option is used in "mac" mode. If specified, it limits the output to a list of MAC addresses to those associated with a single access point (wireless network) having the specified BSSID value. If this option is omitted, then all MAC addresses will be shown.
[-rd DEVICE] | [--ram-device DEVICE]: Use this optional parameter to change the default RAM device that will be used for setting up the runtime environment by the nstkismet script. The following RAM device names are available on NST: /dev/ram0 - /dev/ram9. A corresponding mount point path: /mnt/ram0 - /mnt/ram9 will be automatically selected for the RAM device. One can use the following optional parameter: [-rmp PATH] to change the mount point path location for the selected RAM device. If not specified, a reasonable default value for the nstkismet script shall be chosen.
[-rds SIZE] | [--ram-disk-size SIZE]: Use this optional parameter to change the default RAM disk size in MegaBytes (MB) that will be used if a RAM disk is created by the nstkismet script. **Note: Use a reasonable value and make sure you to not exceed your available system RAM. The system memory utility: "free" can be used to help make your determination. If omitted, a reasonable value will be chosen by the nstkismet script. The minimum value permitted is 10. The maximum value permitted is 1024.
[-rmp PATH] | [--ram-mount-point PATH]: Use this optional parameter to change the selected RAM device: [-rd DEVICE] mount point path location for the runtime environment created by the nstkismet script.
[-rdir DIRECTORY] | [--runtime-directory DIRECTORY]: One can use this optional parameter to force the nstkismet script to use an existing runtime directory on a locally attached disk drive or a mounted network file system and bypass the creation of a RAM disk. To do this, make sure the directory initially exists prior to using this option. If omitted and the -rd DEV option is omitted, then the nstkismet will make a "smart choice" as to whether to allocate a RAM disk or use a existing directory.
[-h [true]|false] | [--help [true]|false]: When this option is specified, nstkismet will display a short one line description of nstkismet, followed by a short description of each of the supported command line options. After displaying this information nstkismet will terminate.
[-H [true]|false] | [--help-long [true]|false]: This option will attempt to pull up additional nstkismet documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.
[-v [true]|false] | [--verbose [true]|false]: When you set this option to true, nstkismet will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.
[--version [true]|false]: If this option is specified, the version number of the script is displayed.

Files

/lib/systemd/system/kismet.service: This systemd unit control is used to start/stop the kismet_server as a systemd service. This script is created when nstkismet is invoked with the --mode setup option and removed when nstkismet is invoked with the --mode remove option.
/var/nst/kismet: This is the default directory which will be used to store information collected by the kismet_server.

Environment

TEXTBROWSER: This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).