A Python client for the Kismet server protocol
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
kismetclient Remove an unnecessary dict comprehension. Oct 11, 2012
.gitignore
LICENSE Update license Apr 19, 2013
README.md
runclient.py whitespace cleanup, remove unused import Sep 16, 2012
setup.py

README.md

kismetclient

A Python client for the Kismet server protocol.

Start by creating a client:

from kismetclient import Client as KismetClient

address = ('127.0.0.1', 2501)
k = KismetClient(address)

Then register any desired builtin protocol handlers:

from kismetclient import handlers
k.register_handler('TRACKINFO', handlers.print_fields)

Create and register a custom protocol handler:

def handle_ssid(client, ssid, mac):
    print 'SSID spotted: "%s" with mac %s' % (ssid, mac)
k.register_handler('SSID', handle_ssid)

and call the listen() method in a loop:

while True:
    k.listen()

The listen() method will retrieve responses from the kismet server, parsing them, and calling registered handlers as appropriate.

kismetclient is agnostic about how you loop this call; choose a method that works well with the rest of your application's architecture. You could run it in a separate blocking thread that handles events by parsing them and pushing to a queue, or you could use gevent to avoid blocking during the socket read call.

A handler is a callable whose first argument is the client generating the message, with all other arguments named after kismet's protocol capabilities. A handler may specify just client and **fields parameters in order to get all fields for a message in the default order. In general, your handlers should be quick to run and not depend on other blocking code.

Handlers are registered by calling the register_handler method on the client. The first argument is the name of the protocol to handle, the second is the function to handle it. It is valid to register a handler for a protocol which is already handled - in this case the new handler overrides the old one.

Commands can be sent using client.cmd(cmd, *args):

k.cmd('ENABLE', protocol, fields)

The first argument is the kismet command name, followed by the command arguments.

A trivial example application is included in runclient.py. Reading the source is also likely to be helpful.

To discover which protocols and capabilities your kismet server supports, start the kismet server and use the interactive python shell:

>>> from kismetclient import Client
>>> k = Client()
>>> k.protocols.keys()
['CRITFAIL', 'ACK', 'PACKET', 'NETTAG', 'BTSCANDEV', 'CAPABILITY',
'SOURCE', 'COMMON', 'CLISRC', 'TRACKINFO', 'PROTOCOLS', 'BSSIDSRC',
'STATUS', 'WEPKEY', 'STRING', 'SPECTRUM', 'ERROR', 'CHANNEL', 'GPS',
'INFO', 'SSID', 'BSSID', 'PLUGIN', 'BATTERY', 'TERMINATE', 'REMOVE',
'ALERT', 'KISMET', 'CLIENT', 'TIME', 'CLITAG']
>>> k.protocols['GPS']
['lat', 'lon', 'alt', 'spd', 'heading', 'fix', 'satinfo', 'hdop',
'vdop', 'connected']

To discover Kismet commands, grep the Kismet source for RegisterClientCommand. At the time of this writing, this list included: CAPABILITY, ENABLE, REMOVE, SHUTDOWN, ADDTRACKERFILTER, ADDNETCLIFILTER, ADDNETTAG, DELNETTAG, ADDCLITAG, DELCLITAG, ADDSOURCE, DELSOURCE, RESTARTSOURCE, HOPSOURCE, and CHANSOURCE. For usage, consult the source or monitor an interactive session between the official client and server using wireshark.

This software is developed using Python 2.7 and the master branch of Kismet. It may also work on Python 2.6 and earlier versions of Kismet, but ymmv. Please open tickets for bugs using github.