Device rules

Added: after 2026-10-R1

Device rules match devices on the server, as they’re seen, and act on the devices which match: they can tag devices, give them a highlight color, collect them into a device view, raise an alert when a device starts matching, and send matching devices to a webhook. Sorts, written in the same language, order the devices in a device view.

Rules are written in a small language, and are compiled to native code where the platform allows it, so a large number of rules can be checked against a large number of devices.

Rules can be loaded from rules files, from the Kismet config, and from the REST API.

Writing rules

Each rule has a name, a condition, and what to do with devices which match it:

rule <name> {
    when <condition>
    description "<text>"
    tag "<text>"
    color "#rrggbb"
    view "<description>"
    alert
    live
    exclude
    recheck <time>
    webhook "<endpoint>" { ... }
}
  • when is the condition a device must match.
  • description says what the rule finds, in at most 1024 characters; the web UI shows it with the rule’s tags.
  • tag tags matching devices; a rule can have any number of tags.
  • color gives matching devices a highlight color, which the web UI also uses for the rule’s tags. When a device matches several rules with colors, the first rule wins.
  • view collects matching devices in the device view rule-<name>, with the description as the view name; without one, the view takes the rule’s description, or Devices matching rule <name>.
  • alert raises a DEVICERULE alert when a device starts matching the rule.
  • live checks the rule on every packet which updates a device, as well as on the timer.
  • exclude leaves matching devices out of the default view. Added after 2026-10-R1.
  • recheck sets how often devices which haven’t changed are checked against a rule whose condition changes over time, from 1 second to 7 days. Added after 2026-10-R1.
  • webhook sends matching devices to a webhook endpoint; see webhooks below.

The default view

After 2026-10-R1, the device view default holds every device which no exclude rule matches, and the web UI lists it as Default, the view the device list opens on. New devices are in it until the rules have checked them. Devices carry kismet.device.rules.excluded while an exclude rule matches them, and leave the default view; every device stays in All devices and the other views.

A rule which only excludes needs no tag or view. For example, to hide the devices you tag hide in the web UI:

rule hidden {
    description "Devices tagged 'hide' in the web UI"
    when has_tag("hide")
    exclude
}

Fields

Conditions compare device fields to values. Fields are Kismet field names, such as kismet.device.base.manuf, or a path through nested fields joined with / (with no spaces), such as kismet.device.base.signal/kismet.common.signal.last_signal. A path through a list or a map of records matches when any of the records match, including the records in a map of lists, such as dot11.device/dot11.device.wpa_handshake_list/dot11.eapol.message_num. Field names may start with digits, as in 802154.device/802154.device.key_state, and paths can go through fields which point at another record, such as dot11.device/dot11.device.last_beaconed_ssid_record/dot11.advertisedssid.ssid.

The devices API shows which fields a device has.

The common fields have short names:

Short nameField
macMAC address
nameDevice name
phyPhy name, such as IEEE802.11
typeDevice type, such as Wi-Fi AP or Apple Watch
simple_typeAfter 2026-10-R1: the basic type of the device’s phy, such as Wi-Fi or BTLE
manufManufacturer
cryptEncryption
channelChannel
frequencyFrequency
packetsTotal packets
datasizeTotal data
first_timeTime first seen
last_timeTime last seen
mod_timeTime last changed
num_alertsNumber of alerts
signalLast signal
min_signalWeakest signal
max_signalStrongest signal
seenbyData sources which saw the device
locationAverage location, as [lon, lat] (after 2026-10-R1)
last_locationLast location, as [lon, lat] (after 2026-10-R1)

A comparison with a field the device doesn’t have is false.

Alerts

After 2026-10-R1, alerts are linked to the devices they name, in kismet.device.base.alerts. The device which sent an alert (its source, or its BSSID when it has no source) is counted apart from the devices the alert only names, since an alert can name its victim: a spoofed deauthentication flood names the access point it claims to be.

Short nameField
num_alertsAlerts naming the device, sent or not
alerts_sentAlerts the device sent
alerts_namedAlerts naming the device which another device sent
alertsNames of the alerts naming the device, such as DEAUTHCODEINVALID
sent_alertsNames of the alerts the device sent
sent_alert_classesClasses of the alerts the device sent, such as EXPLOIT or DENIAL
alert_severityHighest severity of the alerts the device sent: 0 info, 5 low, 10 medium, 15 high, 20 critical
alert_timeTime of the last alert naming the device
sent_alert_timeTime of the last alert the device sent
own_alertsAlerts the device sent outside the classes in device_rules_alert_ignore_classes (DENIAL and SYSTEM by default)
own_alert_severityHighest severity of those alerts

Alert names and classes match in any case. Up to 32 names and classes are kept per device.

alert_severity and sent_alert_classes are kept over all of a device’s alerts, so a condition on both can’t tell a device which sent a high-severity DENIAL alert and a low EXPLOIT one from a device which sent a high EXPLOIT alert. own_alerts and own_alert_severity count each alert’s severity with its own class, leaving out the ignored classes.

Values and operators

  • Numbers compare with ==, !=, <, <=, >, and >=, and can be calculated with +, -, *, /, and %. Put spaces around / for division, so it isn’t read as a field path.
  • Durations such as 30s, 5m, 2h, and 1d are numbers of seconds. now is the current time, and age(field) is now - field.
  • After 2026-10-R1, lat(field) and lon(field) are the latitude and longitude of a location, such as lat(location). A device without a location doesn’t match.
  • Strings compare with == and !=, or with contains, icontains (in any case), startswith, endswith, and matches (a PCRE regular expression), against a "string". After 2026-10-R1, ==, !=, and in on the device type (type and simple_type) ignore case, so type == "wi-fi ap" matches Wi-Fi AP; other strings match exactly.
  • type is what the device is, such as Wi-Fi AP; after 2026-10-R1, simple_type is the basic type of its phy, such as Wi-Fi, for matching every device of a kind: simple_type == "BTLE" matches Apple Watches, trackers, and every other BTLE device.
  • MAC addresses are written aa:bb:cc:dd:ee:ff, with an optional mask as /24 or /ff:ff:ff:00:00:00; a short address such as aa:bb:cc matches the prefix.
  • x in [a, b, c] and x not in [a, b, c] test against a list of values. A field which holds several values, such as sent_alert_classes, is in a list when any of its values is, so not in means none of them are.
  • exists(field) tests that a field is present, and count(field) counts the entries in a list or map.
  • After 2026-10-R1, has_tag("name") tests that a device has the user tag name, as set from the device details or with /devices/by-key/<key>/set_tag.cmd (tagname and tagvalue). Tags are saved with a device’s name and notes, so they last across restarts; ephemeral tags, which last until Kismet restarts, count the same.
  • After 2026-10-R1, tag_time("name") is the number in the user tag name, such as the time in baseline. A device without the tag, or whose tag isn’t a number, doesn’t match.
  • After 2026-10-R1, start_time is when Kismet started, and uptime is now - start_time.
  • After 2026-10-R1, hours_active counts the hours of the last 24 the device was heard, from 0 to 24, and days_active the days of the last 7, from 0 to 7. Both only count the time Kismet has been running. hours_active reads the device’s packet history (track_device_rrds, on by default); days_active is only recorded with device_rules_baseline=true.
  • After 2026-10-R1, in_baseline(field) tests that the device whose MAC address is in field is in the baseline, such as in_baseline(dot11.device/dot11.device.last_bssid) for clients of access points in the baseline. An access point is its own last BSSID, so it matches too.
  • After 2026-10-R1, random_address matches Wi-Fi devices with a randomized MAC address and BTLE devices with a resolvable or non-resolvable random address, and linked matches devices linked to another address of the same device.
  • Conditions combine with and, or, not, and parentheses.

Conditions that change over time

Rules are checked against the devices which changed since the last check, every device_rules_interval. Only changed devices are read, so this costs little however many devices there are.

A condition using now, age(), uptime, hours_active, days_active, or in_baseline() can start or stop matching without the device changing, so devices which haven’t changed are checked against those rules again every device_rules_full_interval, or as often as the rule’s recheck says:

rule gone-quiet {
    when age(last_time) > 10m and packets > 1000
    recheck 1m
    tag "quiet"
}

recheck is only allowed on rules with such a condition; on any other rule it’s an error.

These checks read every device. On 100,000 devices a pass takes about 80 ms on a fast desktop and roughly half a second on a Raspberry Pi 4, so on large or slow systems use the longest recheck and device_rules_full_interval that work. Checks happen on the device_rules_interval timer, so a time shorter than that acts as that.

Including other files

A rules file can read in other rules files, relative to itself:

include "<file>"
include "<dir>/*.rules"

A pattern reads every matching file in natural order, so 2_x.rules comes before 10_x.rules.

Sorts

Sorts order the devices in a device view:

sort <name> {
    by <value> [asc|desc], <value> [asc|desc] ...
}

A value is a field or a calculation on fields, a true / false condition (false sorts first), or rule, the position of the first rule the device matches. Later values break ties in earlier ones, and devices missing a value sort after the rest in either direction.

A device view is sorted by passing the sort name as rule_sort, as in /devices/views/all/devices.json?rule_sort=<name>.

Device view filters

After 2026-10-R1, device views also take a condition and sort keys directly, without a named rule or sort, as filter=<condition> and filter_sort=<value> [asc|desc], .... The new web UI’s device list search box sends these; see device filters for the short form it takes.

In a filter, text("<s>") matches devices where any text field the request asks for (its fields list) contains s, in any case. text() can only be used in view filters, not in rules.

Examples

rule close-apple {
    when manuf contains "Apple" and signal > -60
    tag "close"
}

rule watchlist {
    when mac in [00:11:22:33:44:55, aa:bb:cc/24]
    tag "watchlist"
    view "Devices on the watch list"
    alert
    live
}

rule open-ap {
    when type == "Wi-Fi AP" and crypt == "Open"
    tag "open"
}

rule free-ssid {
    when dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid icontains "free"
    tag "free wifi"
}

rule gone-quiet {
    when age(last_time) > 10m and packets > 1000
    tag "quiet"
}

rule quad {
    when lat(location) >= 10.0 and lat(location) <= 10.1 and lon(location) >= 20.0 and lon(location) <= 20.1
    tag "quad"
    view "Devices in the quad"
}

sort loudest {
    by signal desc, packets desc
}

sort by-rule {
    by rule, last_time desc
}

Webhooks

A webhook statement sends devices which match the rule to an endpoint defined by a webhook_endpoint line in the config. By itself, it sends a device when it starts matching; terms in braces change when it sends, and what:

webhook "<endpoint>" {
    trigger match | new | once | every <time> | change <field>, ... limit <time>
    for <time>
    stop
    rate <n>/<period> [burst <n>]
    batch <time> [max <n>]
    fields <field>, ...
    fire_existing
}
Term
trigger matchWhen a device starts matching; the default. It’s sent again only after it stops matching and matches again.
trigger newWhen a device first seen after the rule loaded starts matching, once per device.
trigger onceThe first device to match, once. Loading the rules again keeps it used, as long as the rule keeps its name and the webhook keeps its trigger and its place in the rule.
trigger every <time>While a device matches, each time it’s updated, at most once per <time>, which must be 10 seconds or more.
trigger change <field>, ... limit <time>When the fields change while a device matches, at most once per <time> per device, which must be 1 second or more; the limit is required. Fields are single values, such as signal or name; a field which is a record or a list, such as dot11.device or seenby, is refused. Changes within the limit are sent together when it’s up, with the old and new values. Up to 8 fields.
for <time>A device must keep matching this long before it’s sent.
stopAlso send when a device stops matching. Not with trigger once.
rate <n>/<period> [burst <n>]The most events from this webhook per period, such as 10/1m or 100/1h. Default 10/1m.
batch <time> [max <n>]Hold events to send together: the first event opens a window, which is sent when <time> is up or <n> events are in it (default 100).
fields <field>, ...The device fields to send, as the short field names rules use (mac, name, signal) or full field names and paths, as in the REST API’s fields; up to 32. The default is the device key, MAC, name, phy, type, simple type, manufacturer, channel, frequency, first and last time, and last signal.
fire_existingAlso send devices which already match when the rule loads; without it they’re recorded and not sent.

A rule can have up to 4 webhook statements. The endpoint’s own rate, queue, and retry limits apply on top of the rule’s, along with webhook_global_rate; /webhooks/status.json shows what each webhook sent and held back.

trigger new goes by the time a device was first seen, so devices in an old pcap replayed into Kismet aren’t new.

rule new-public-btle {
    description "New BTLE devices with public addresses"
    when phy == "BTLE" and not exists(btle.device.random_address_type)
    webhook "ha" {
        trigger new
        batch 30s max 100
        fields mac, name, signal
    }
}

rule watchlist-signal {
    when mac in [00:11:22:33:44:55]
    webhook "ha" {
        trigger change signal limit 30s
        stop
    }
}

Limits

  • An expression can have at most 256 operators, nested at most 64 deep.
  • Rules set over the API can be at most 256KB of text.
  • All of the rules together can make at most 256 views.

Shipped rules

Kismet ships rules for notable devices in kismet_device_rules_highlights.txt, grouped by phy. Each tags the devices it matches and collects them in a view:

RuleMatchesTagView
wpa-handshakeWi-Fi networks with WPA handshake messages 1 and 2, or 2 and 3 (possibly from different clients)handshakeWPA Handshakes
pmkidWi-Fi networks with an RSN PMKIDpmkidRSN PMKID
zigbee-known-key802.15.4 devices using a known or exposed keyzigbee keyZigbee Known Keys
adsb-governmentAircraft owned by government agencies, police, and the militarygovernmentADS-B Government Aircraft
ais-emergencyAIS search and rescue transponders, man overboard devices, and emergency beaconsais emergencyAIS Emergency
uavDrones Kismet recognizes, on any phyuavUAV / Drones
bodycamBody cameras, by address or namebodycamBodycams
apple-continuityBluetooth devices sending Apple Continuity messages; the row highlight starts off in the web UIapple continuityApple Continuity Devices
btle-related-old-addressBTLE random addresses replaced by a newer address with the same payload; excluded from the default viewold address
btle-related-unmatchedBTLE rotating random addresses whose payload no other address shares; excluded from the default view

The two btle-related rules, added after 2026-10-R1, only match when BTLE related devices are turned on; btle-related-unmatched also needs btle_random=hide_unmatched.

A rule with the same name in a later file, such as kismet_device_rules.txt, replaces the shipped one; device_rule_disable=<name> leaves one out.

Device baseline

After 2026-10-R1, the device details in the web UI have a Baseline row: Add to baseline marks a device as one you know, with the user tag baseline (its value is the time it was added), and Remove from baseline takes it out. The rules which use it, making the Baseline devices and Unknown devices views, leaving the baseline out of the default view, and highlighting it, are in kismet_baseline_rules.txt, with the baseline filters which can build the baseline on their own; see device baseline.

Rules see a device join or leave the baseline at once, as do rules that test a device’s name, when it’s renamed. To alert when a device outside the baseline appears, add a rule of your own, such as:

rule unknown-ap {
    description "Access points not in the baseline"
    when type == "Wi-Fi AP" and not has_tag("baseline")
    alert
}

Loading rules

Rules are read from rules files, then from directories of rules files, then from plugins, then from device_rule and device_sort lines in the config, and then from the REST API, in that order. The order sets which rule’s color wins and how by rule sorts.

A rule or sort with the same name as one read earlier, from another file, replaces it in its place; the same name twice in one file is an error. If any rule has an error, none of the rules are loaded, and the error is reported with its file and line.

After 2026-10-R1, plugins can ship rules files, in the order the plugins load, after the rules files and directories. Plugin rules are built in once every plugin has loaded, so they can use the fields plugins add, and each plugin’s rules are checked on their own: a plugin whose rules have an error is left out, with the error logged, and the other rules still load. A device_rule line or a rule set over the API can replace a plugin’s rule by name.

The device rules options are in kismet_device_rules.conf; as with other options, changes are best made in kismet_site.conf.

device_rules_file={ path }

Rules files, in order. Use += in kismet_site.conf to add a file, or = to replace the list. Without any, %E/kismet_device_rules_highlights.txt (the shipped rules), %E/kismet_device_rules.txt, and, after 2026-10-R1, %E/kismet_baseline_rules.txt (the baseline views and filters) are read, in that order, if they exist; kismet_device_rules.txt describes the rules language, and holds examples which are commented out. Setting device_rules_file replaces all of them, so list them again to keep them:

device_rules_file=%E/kismet_device_rules_highlights.txt
device_rules_file+=%E/kismet_device_rules.txt
device_rules_file+=%E/kismet_baseline_rules.txt
device_rules_file+=/etc/kismet/site.rules

device_rules_dir={ path }

A directory of rules files; every *.rules file in it is read, in natural order.

device_rules_dir=%E/device_rules.d

device_rule={ rule }

A rule on one line, written without its leading rule. Long rules are better kept in a rules file; config lines can’t be longer than 8190 characters.

device_rule=close-apple { when manuf contains "Apple" and signal > -60 tag "close" }

device_sort={ sort }

A sort on one line, written without its leading sort.

device_sort=loudest { by signal desc, packets desc }

device_rule_disable={ name }

Leave out a rule by name, such as one from a packaged rules file or a plugin. A name which matches no rule is reported in the log once the plugins have loaded.

device_sort_disable={ name }

Leave out a sort by name, including a plugin’s.

device_rules_disabled_file={ path }

Rules switched off from the web UI or the REST API are kept off across restarts: their names are saved in this file, one per line, by default %h/.kismet/kismet_device_rules_disabled.txt. A rule that’s switched off isn’t checked, and its tags, color, view, alerts, and webhooks go with it; it’s still listed, as off. A name stays in the file while its rule is missing, so the rule is off again when it comes back. Added after 2026-10-R1.

To leave a rule out from the config instead, use device_rule_disable.

device_rules_api_save={ true } / { false }

Rules set over the REST API are kept in memory unless saved. When saved, they’re written to device_rules_api_file and loaded again at startup. By default, they aren’t saved.

device_rules_api_file={ path }

Where rules set over the REST API are saved, by default %h/.kismet/kismet_device_rules_api.txt.

device_rules_interval={ time }

How often rules are checked against the devices which changed since the last check, by default every second. Rules marked live are also checked on every packet which updates a device. After 2026-10-R1, this is a time such as 1s or 5s, from 1 second to an hour (a bare number is seconds), and only the changed devices are read.

device_rules_full_interval={ time }

How often devices which haven’t changed are checked against the rules whose conditions change over time, by default every 10 seconds; a rule’s recheck sets its own time. 0 never checks unchanged devices. Devices which haven’t changed are only checked against those rules; the other rules keep their last result, and their webhooks with every, change, or for only repeat when the device changes.

It’s a time such as 10s or 5m, from 1 second to 7 days; a bare number is seconds. Earlier development builds took a number of device_rules_interval checks instead. Each of these checks reads every device, so on large or slow systems keep it long.

A value which isn’t a valid time, or is out of range, is reported in the log, and the default is used.

device_rules_alert_backlog={ count }

The most DEVICERULE alerts held back by the alert rate limit at once, by default 64. Held-back alerts are raised as the limit allows, and when the queue is full the oldest is dropped. 0 drops held-back alerts.

The rate limit is set like other alerts, with alert=DEVICERULE,... in kismet_alerts.conf.

device_rules_jit={ true } / { false }

Compile rules to native code where the platform allows it (64-bit x86, ARM, RISC-V, PowerPC, MIPS, s390x, and LoongArch). Elsewhere, or when the system forbids generated code, rules run in the bytecode interpreter with the same results. By default, rules are compiled.

Rules in the web UI

The device list has a Tags column, which can be searched and sorted, and the device details list a device’s tags first, with the rules that set them and their descriptions; rules which only make a view, with no tag, color, or alert, aren’t listed there. Views made by rules are listed with the other device views, with how many devices they hold.

Rows in the device list are highlighted by their tags, under Settings, Device Highlights. Each tag takes the color of its rule, or a default color for the tags of the shipped rules and the examples, and the color can be changed there. Tags can be dragged into priority order: a device with several tags takes the color of the highest one.

After 2026-10-R1, Device rules in the main menu lists the loaded rules and sorts, grouped by where they came from: each rules file, the config file, each plugin, and the rules set over the API. Each rule shows the tags it sets and the view it makes; clicking the view opens the device list on it. A rule can be opened to show its description, color, whether it is live or raises an alert, the file and line it came from, and its text. All, Tagging, and Views list every rule, only the rules which tag devices, or only the rules which make views. Rules which replaced an earlier rule of the same name are noted, and Reload reads the list again.

After 2026-10-R1, each rule in the window shows how many devices it matches, kept up to date while the window is open, and has a switch to turn it off and back on; rules switched off stay listed, and stay off across restarts (see device_rules_disabled_file). The device list opens on the Default view, which leaves out the devices exclude rules match; All devices still lists everything. The Baseline tab lists the baseline filters, with how many devices each has added to or removed from the baseline, in place of a match count.

The legacy UI picks tag colors under Settings, Rule tags, with defaults for the tags of the shipped rules; if the colors were already changed there, the saved list is kept, and new tags need to be added to it.

Rules in the REST API

The device rules API lists, checks, sets, and tests rules, and devices which match rules carry kismet.device.base.rules.