Tuesday, June 6, 2017

Kismet Plugins - Web-only Plugins

The new Kismet plugin architecture is beginning to solidify, and as part of that, the ability to create plugins which only affect the Web UI is now in place.

If your plugin idea doesn't require any changes to how Kismet itself functions, and only modifies or adds to the Web UI, you can now do it as a runtime-loaded add-in with no C++ coding at all, and only minimal modification of the example Makefile.

The example code is in Kismet git under plugin-demo-webonly; you can browse it at https://github.com/kismetwireless/kismet/tree/master/plugin-demo-webonly .

All plugins, regardless of if they use C++ native code or only extend the web UI, have 2 files which must be present:
  1. Makefile, which tells the build system how to compile.  For web-only plugins this file is very simple, and the only change that needs to be made is changing the name of the plugin on the first line (PLUGIN_NAME ?= ...).  This plugin name is used to control the directory the plugin is installed into.
  2. manifest.conf, which tells Kismet about the plugin.  This is a simple config file that is very similar to the Kismet config files; it contains the name, description, author information, version information, and module information.
For a web-only plugin, the manifest only needs to define the name, version, description, and author fields.  To tell Kismet to load a JS object when the web UI is loaded, there also needs to be a 'js' parameter.

Plugins are automatically mapped into the Kismet webserver, serving content from [plugindir]/[pluginname]/httpd/ on the filesystem to the URL /plugin/[pluginname]/.  The plugin directory is automatically determined and mapped, regardless if it is installed system-wide or in a user directory; This means you can serve full content from your plugins httpd/ directory.

To dynamically load JS modules, Kismet expects a few standard conventions - the demo JS file in the example plugin shows the minimal basics, but for more information about how to automatically interface with the Kismet web UI framework, check out some of the developer docs:

  • webui_rest.md explains how to use various endpoints in Kismet to get additional data
  • webui.md explains the format of Javascript modules and how to hook into existing functions in the Kismet UI, like adding settings panels, sidebar triggers, tabbed frames, etc
  • device_data.md explains how to add additional details to the Kismet device details windows, which are shown when you click on a device.

A huge thanks to all who support Kismet on Patreon - if you'd like to help, you can become a patron here!