pax_global_header00006660000000000000000000000064137236265160014525gustar00rootroot0000000000000052 comment=49435373050102eda7c42fb64c6e190b3a052cf4 kismet-docs-master/000077500000000000000000000000001372362651600146045ustar00rootroot00000000000000kismet-docs-master/devel/000077500000000000000000000000001372362651600157035ustar00rootroot00000000000000kismet-docs-master/devel/.gitignore000066400000000000000000000000101372362651600176620ustar00rootroot00000000000000.*.swp* kismet-docs-master/devel/adding_tag_parsers.md000066400000000000000000000326021372362651600220500ustar00rootroot00000000000000--- title: "Extending device and data tracking" permalink: /docs/devel/dot11_ie_parsers/ toc: true docgroup: "devel-cpp" excerpt: "How to extend the Kismet interface for parsing 802.11 IE tags." --- Adding parsers for new IE tags in Kismet is relatively simple; there's a handful of files you need to modify and coding conventions you should follow, however. ## Kaitai Kismet uses the [Kaitai](https://kaitai.io) library for processing stream data, however it does *not* (currently) use the Kaitai parser generator. Kismet parsers are written manually, mostly because of the difficulty of generating long-lifecycle code safely from KaitaiStruct templates; errors encountered in the stream could leave memory leaks which were unrecoverable. The Kaitai stream library contains safe mechanisms for accessing elements of various types in a stream. If the stream is unable to satisfy the requested data, an exception is raised. All interaction with tag parsers should be wrapped in `try/catch` blocks, and a tag parser is free to throw exceptions as necessary. ## Tags IE tags are found in various management frames: Beacons, probe responses, probe requests, association responses, and more. They are a list of fields, each field containig a tag number, tag length, an the tag data. The Kismet tag parser will break tags into independent values automatically, assigning a Kaitai stream to the data of each tag. An IE tag parser needs to only worry about the data! ## Parser header The tag (and other parsers) for 802.11 packets are kept in `dot11_parsers/`. A theoretical parser, at its simplest, would be defined as: ```c++ class dot11_ie_12345_fake { public: dot11_ie_12345_fake() { } ~dot11_ie_12345_fake() { } void parse(std::shared_ptr p_io); constexpr17 uint8_t fake_value() const { return m_fake_value; } constexpr17 uint16_t fake_twobyte() const { return m_fake_twobyte; } protected: uint8_t m_fake_value; uint16_t m_fake_twobyte; }; ``` IE field parsers are named after the IE tag and the common name: `dot11_ie_*tagnum*_*tag name*`; for instance `dot11_ie_11_qbss` or `dot11_ie_221_vendor`. While verbose, this makes reading the code which uses the parsers FAR simpler in the future. The constructor and destructor are empty - a tag parser, typically, should not define any dynamic memory that is not managed by smart pointers such as `shared_ptr`. The accessor functions are, typically, defined using the Kismet workaround for variable `constexpr` support. `constexpr17` is defined by Kismet in `multi_constexpr.h` and evaluates to `constexpr` only if the compiler supports C++17 or newer. Accessors should be named after the field they return, which should in turn be named after the field definition in the protocol specification. The field variable names should follow the Kaitai auto-generated code convention of beginning with `m_` and being named after the field they are derived from. Typically, the accessors are defined entirely in the header file, while the `parse` function is defined in the source file. ## Parser source Generally, the `parse(...)` function is the only function defined in the source. For our fake tag, we assume a tag contains an 8 bit unsigned value, and a 16 bit unsigned value. The 16 bit value is encoded as little-endian. ```c++ dot11_ie_12345_fake::parse(std::shared_ptr p_io) { m_fake_value = p_io->read_u8(); m_fake_twobyte = p_io->read_u2le(); } ``` Notice that we don't need to check the length of the fields; the Kaitai stream library handles this for us automatically. Since the stream buffer is created with the tag data and the specified tag length, the parser does not need to worry about running into the next tag, nor running into the end of the packet headers. ## A more complex example Let's look at the IE 11 QBSS source for a slightly more complex example: ```c++ #include "dot11_ie_11_qbss.h" #include "fmt.h" void dot11_ie_11_qbss::parse(std::shared_ptr p_io) { // V1 if (p_io->size() == 4) { m_station_count = p_io->read_u2le(); m_channel_utilization = p_io->read_u1(); m_available_admissions = p_io->read_u1(); return; } // V2 if (p_io->size() == 5) { m_station_count = p_io->read_u2le(); m_channel_utilization = p_io->read_u1(); m_available_admissions = p_io->read_u2le(); return; } throw std::runtime_error(fmt::format("dot11_ie_11_qbss expected v1 (4 bytes) or v2 (5 bytes), " "got {} bytes", p_io->size())); } ``` The QBSS tag may take 2 forms, depending on version; the only way to determine which form is in play is to check the size of the stream buffer. For version 1, 4 bytes are read, while for version 2, 5 bytes are read. The parser throws an exception if the buffer is not either 4 or 5 bytes long. Typically, a parser may use Kaitai stream processing to handle raising the exception, but because the QBSS tag version is length-dependent, we explicitly raise an exception if an invalid length was found. ## 150 and 221 vendor tags The IE150 and IE221 tags are somewhat special: Both define vendor extensions, which are then nested under an OUI and sub-type record. Typically IE150 holds Cisco-specific data about the access point configuration, while IE221 is a catch-all for WMM, QoS, encryption settings, unique vendor tags, and other unique vendor data. The parsing of the IE150 and IE221 tags is handled by Kismet, breaking each tag into sub-tags, similar to how Kismet breaks the IE data into individual fields. Kismet extracts the vendor OUI and subtype, and starts the sub-tag stream immediately *after* the OUI record. Sub-tag parsers *must process the subtype byte*, as not all sub-types *use* a type byte. Subtypes are defined the same way as IE parsers, with a few additional values; using the `dot11_ie_221_ms_wps` sub-type parser as an example: ```c++ constexpr17 static uint32_t ms_wps_oui() { return 0x0050f2; } constexpr17 static uint8_t ms_wps_subtype() { return 0x04; } ``` Each subtype should export a static integer version of the vendor OUI, and if applicable, the subtype. This allows the consuming code to quickly compare subtypes to apply the parser. The parse function is implemented the same as before, with the additional consumption of the 1 byte value. Using our previous example of parsing a 1 byte and 2 byte value, as a 221 subtype: ```c++ dot11_ie_221_fake_sub::parse(std::shared_ptr p_io) { // read and throw away the subtype p_io->read_u8(); // Read the content m_fake_value = p_io->read_u8(); m_fake_twobyte = p_io->read_u2le(); } ``` ## Nested complexity Some elements themselves include a list of data; for example the IE221 MS-WPS tag contains a list of sub-elements. Typically these should be defined as sub-classes, each with their own `parse(...)` function. This allows consistent naming and stream validation. Nested vectors or maps of data *should always use smart pointers*. This *ensures that memory is not lost in the parsing of tags*. Looking again at the relevant portions of `dot11_ie_221_ms_wps`: ```c++ class dot11_ie_221_ms_wps { public: class wps_de_sub_element; typedef std::vector > shared_wps_de_sub_element_vector; dot11_ie_221_ms_wps() { } ~dot11_ie_221_ms_wps() { } void parse(std::shared_ptr p_io); ... protected: uint8_t m_vendor_subtype; std::shared_ptr m_wps_elements; ... ``` Later in `dot11_ie_221_ms_wps` we define the sub-element class: ```c++ public: class wps_de_sub_element { public: class wps_de_sub_common; class wps_de_sub_string; class wps_de_sub_rfband; class wps_de_sub_state; class wps_de_sub_uuid_e; class wps_de_sub_vendor_extension; class wps_de_sub_version; class wps_de_sub_primary_type; class wps_de_sub_ap_setup; class wps_de_sub_generic; ... wps_de_sub_element() {}; ~wps_de_sub_element() {}; void parse(std::shared_ptr p_io); constexpr17 wps_de_type_e wps_de_type() const { return (wps_de_type_e) m_wps_de_type; } ... } ``` The WPS definitions are very convoluted - the `de_sub_element` in turn defines a number of additional classes. While verbose, this methodology is at least consistent, readable, and easier to validate. Finally, the parser function: ```c++ void dot11_ie_221_ms_wps::parse(std::shared_ptr p_io) { m_vendor_subtype = p_io->read_u1(); m_wps_elements.reset(new shared_wps_de_sub_element_vector()); while (!p_io->is_eof()) { std::shared_ptr e(new wps_de_sub_element()); e->parse(p_io); m_wps_elements->push_back(e); } } ``` The `parse` function does 3 things: 1. Read the subtype byte. We store this instead of discarding it, in this parser. 2. Zero the vector 3. Iterate over the remaining tag data. It is important to check the stream length here! The data should match the length of the buffer. By checking the length, we *prevent* a false failure when we hit the end of the buffer trying to read another record - but we *also* ensure that the entire buffer is read. ## Bitfields Many tags define bitfields. Generally, it's best to implement the bitfields so that the code using the API calls a function returning a boolean (or a shifted integer for multi-bit values); for instance from `dot11_ie_54_mobility`: ```c++ constexpr17 uint8_t mobility_policy() const { return m_mobility_policy; } constexpr17 unsigned int policy_fastbss_over_ds() const { return mobility_policy() & 0x01; } constexpr17 unsigned int policy_resource_request_capability() const { return mobility_policy() & 0x02; } ``` The general goal is to shift as much of the tag-specific logic into the tag parser, and away from the caller. ## Parsing tags Parsing tags is handled by `phy_80211_dissectors.cc`. The values are put into the procesed `dot11_packinfo` defined in `phy_80211.h`. Processed records can be added to `dot11_packinfo` as data, or as shared pointers to processed tags: ```c++ ... std::shared_ptr dot11ht; std::shared_ptr dot11vht; ... unsigned int ccx_txpower; bool cisco_client_mfp; ... ``` Tag processing happenns in `phy_80211_dissectors.cc` in the `Kis_80211_Phy::PacketDot11IEDissector(...)` function. This function builds the hash of IE tag content and processes the tags by number: ```c++ ... // IE 11 QBSS if (ie_tag->tag_num() == 11) { try { auto qbss = std::make_shared(); qbss->parse(ie_tag->tag_data_stream()); packinfo->qbss = qbss; } catch (const std::exception& e) { fprintf(stderr, "debug - corrupt QBSS %s\n", e.what()); packinfo->corrupt = 1; return -1; } continue; } ... ``` The parser structure breaks each tag apart and iterates over them in the `ie_tag` iterator. To process the content of the tag using our parser, we define our tag and pass the tag stream to the parser. For QBSS, we use smart pointers to keep a copy of the tag in the `packinfo` record. ## Adding tags to devices To add tags to devices, a new `TrackedElement` field must be added to the appropriate object in the device record; these are generally defined in `phy_80211.h`. You will need to define the proper `__Proxy`` functions and registration functions, as described in [Extending device and data records](/docs/devel/data_types): ```c++ class dot11_advertised_ssid : public tracker_component { public: ... __Proxy(cisco_client_mfp, uint8_t, bool, bool, cisco_client_mfp); ... protected: virtual void register_fields() override { ... RegisterField("dot11.advertisedssid.cisco_client_mfp", "Cisco client management frame protection", &cisco_client_mfp); ... } ... // Cisco frame protection std::shared_ptr cisco_client_mfp; }; ``` With the field defined, you will then need to extract the data from the `dot11_packinfo` record at the appropriate stage in `phy_80211.cc` and place it in the 802.11 device record. Since IE tags happen in beacons, probes, and associations, there are several places you may wish to add code to handle tags: * `Kis_80211_Phy::HandleSSID(...)` which handles beacons and probe and association responses. * `Kis_80211_Phy::HandleProbedSSID(...)` which handles probe request and association request. For instance: ```c++ void Kis_80211_Phy::HandleSSID(std::shared_ptr basedev, std::shared_ptr dot11dev, kis_packet *in_pack, dot11_packinfo *dot11info, kis_gps_packinfo *pack_gpsinfo) { ... // Set the mobility if (dot11info->dot11r_mobility != NULL) { ssid->set_dot11r_mobility(true); ssid->set_dot11r_mobility_domain_id(dot11info->dot11r_mobility->mobility_domain()); } // Set tx power ssid->set_ccx_txpower(dot11info->ccx_txpower); // Set client mfp ssid->set_cisco_client_mfp(dot11info->cisco_client_mfp); ... } ``` kismet-docs-master/devel/datasource.md000066400000000000000000000741131372362651600203650ustar00rootroot00000000000000--- title: "Creating Kismet datasources" permalink: /docs/devel/datasources/ toc: true docgroup: "devel-cpp" excerpt: "How to extend Kismet by creating new datasources" --- ## Extending Kismet: Creating Capture Sources Kismet supports additional capture types via the `KisDatasource` interface. Data sources run in an independent process and can be written in any language, however they require a C++ component which functions as a Kismet driver to allow it to communicate with the datasource binary. Datasources can report packets or complex records - if your datasource needs to pass parsed information about a device event, that's possible! ## Capture via IPC and Network Kismet datasources communicate from the capture binary to the Kismet server via an IPC channel or TCP connection. This channel passes commands, data, and other objects via an extension of the Kismet External API protocol; written using the Google Protobuf library, this protocol is extensible and parsers can be generated for nearly any language. The datasource IPC channel is via inherited file descriptors: Prior to launching the capture binary, the Kismet server makes a pipe(2) pair and will pass the read (incoming data to the capture binary) and write (outgoing data from the capture binary) file descriptor numbers on the command line of the capture binary. Operating as a completely separate binary allows the capture code to use increased permissions via suid, operate independently of the Kismet main loop, allowing the use of alternate main loop methods or other processor-intensive operations which could stall the main Kismet packet loop, or even using other languages to define the capture binary, such as a Python capture system which utilizes Python radio libraries. The network protocol is an encapsulation of the same protocol over a TCP channel, with some additional setup frames. The network protocol will be more fully defined in future revisions of this document. ## The External Datasource Protocol The datasource capture protocol acts as additional commands within the Kismet External API; it is defined in `protobuf_definitions/datasource.proto`. Datasource commands are in the `KismetDatasource` namespace, and their string equivalents in the helper API are prefixed with `KDS`. Reply-only frames are suffixed with `RESPONSE`. ### KDS Commands #### `KDSCLOSEDATASOURCE` (KismetDatasource.CloseDatasource) *Kismet -> Datasource* Closes the active datasource; this is called during the shutdown process when a source is closed or Kismet exits. ##### Content *None* ##### Reply *None* #### `KDSCONFIGURE` (KismetDatasource.Configure) *Kismet -> Datasource* Configure the behavior of a running source. ##### Content | Field | Type | Content | | -------- | ---------------------------- | ------------------------------------------- | | channel | KismetDatasource.SubChanset | *Optional* Fixed-channel control | | hopping | KismetDatasource.SubChanhop | *Optional* Hopping and channel list control | | spectrum | KismetDatasource.SubSpectrum | *Optional* Spectrum monitoring control | ##### Response `KDSCONFIGUREREPORT` KismetDatasource.ConfigureReport #### `KDSCONFIGUREREPORT` (KismetDatasource.ConfigureReport) *Datasource -> Kismet* Report configuration status and success to Kismet; This report must contain the sequence number of the `KDSCONFIGURE` request in the `success` field. ##### Content | Field | Type | Content | | ------- | ---------------------------- | ------------------------------------------------------------ | | success | KismetDatasource.SubSuccess | Success report for `KDSCONFIGURE` command | | channel | KismetDatasource.SubChannel | *Optional* Channel configuration of datasource | | hopping | KismetDatasource.SubChanhop | *Optional* Hopping configuration of datasource | | message | KismetExternal.MsgbusMessage | *Optional* Message to be sent to the user via the Kismet Messagebus system | | warning | string | *Optional* Warning message about the current configuration, to be placed in the datasource details. | ##### Response *None* #### `KDSDATAREPORT` (KismetDatasource.DataReport) *Datasource -> Kismet* Datasources uses `KDSDATAREPORT` to send packets, signal data, and GPS data to Kismet. The packet payload is mapped to the Kismet datasource, and sent to the packet processing subsystem. ##### Content | Field | Type | Content | | -------------- | ---------------------------- | ------------------------------------------------------------ | | gps | KismetDatasource.SubGps | *Optional* GPS coordinates | | message | KismetExternal.MsgbusMessage | *Optional* Message to be sent to the user via the Kismet Messagebus system | | packet | KismetDatasource.SubPacket | *Optional* Packet content to be injected into the Kismet packetchain | | signal | KismetDatasource.SubSignal | *Optional* Signal or RSSI information which is not part of the packet data or packet headers. | | spectrum | KismetDatasource.SubSpectrum | *Optional* Spectral data | | warning | string | *Optional* Warning message about the datasource, which will be placed into the datasource details | | json | KismetDatasource.SubJson | *Optional* Arbitrary JSON record for non-packet device data | | buffer | KismetDatasource.SubBuffer | *Optional* Arbitrary protobuf record for non-packet device data | | high_prec_time | double | *Optional* high-precision Posix timestamp with nanosecond precision, if available. | ##### Response *None* #### `KDSERRORREPORT` (KismetDatasource.ErrorReport) *Datasource -> Kismet* Fatal error condition which should initiate a datasource shutdown. ##### Content | Field | Type | Content | | ------- | ---------------------------- | ------------------------------------------------------------ | | success | KismetDatasource.SubSuccess | Error condition with failed sequence number (if any) or 0 (if runtime error) | | message | KismetExternal.MsgbusMessage | *Optional* Additional message explaining the failure condition. | ##### Response *None* #### `KDSLISTINTERFACES` (KismetDatasource.ListInterfaces) *Kismet -> Datasource* Request a list of supported interfaces; Kismet uses this to populate the Data Sources display where a user can activate available sources. ##### Content *None* ##### Response `KDSINTERFACESREPORT` KismetDatasource.InterfacesReport #### `KDSINTERFACESREPORT` (KismetDatasource.InterfacesReport) *Datasource -> Kismet* Returns a list of supported interfaces, if the datasource is capable of listing potential sources. ##### Content | Field | Type | Content | | ---------- | ------------------------------- | ------------------------------------------------------------ | | success | KismetDatasource.SubSuccess | Success report for `KDSLISTINTERFACES` command | | message | KismetExternal.MsgbusMessage | *Optional* Message to be displayed regarding interface list or failure | | interfaces | KismetDatasource.SubInterface[] | *Optional* List of interfaces | ##### Response *None* #### `KDSNEWSOURCE` (KismetDatasource.NewSource) *Datasource -> Kismet* Remote captures are multiplexed over a single TCP port; to associate a remote capture with the proper driver code in Kismet, the datasource must send a `KDSNEWSOURCE`. ##### Content | Field | Type | Content | | ---------- | ------ | ------------------------------------------------------------ | | definition | string | Kismet source definition (from the datasource `--source=` command line option) | | sourcetype | string | Kismet datasource type (must match a datasource type) | | uuid | string | UUID of the datasource to be created | ##### Response After receiving and successfully mapping a `KDSNEWSOURCE` to a datasource driver, Kismet will send a `KDSOPENSOURCE` command to being configuration. #### `KDSOPENSOURCE` (KismetDatasource.OpenSource) *Kismet -> Datasource* Kismet will start a datasource by sending a `KDSOPENSOURCE`; this will be sent for an IPC source or a remote capture source which has completed the initial handshake. ##### Content | Field | Type | Content | | ---------- | ------ | ------------------------ | | definition | string | Kismet source definition | ##### Response `KDSOPENSOURCEREPORT` KismetDatasource.OpenSourceReport #### `KDSOPENSOURCEREPORT` (KismetDatasource.OpenSourceReport) *Datasource -> Kismet* A `KDSOPENSOURCEREPORT` carries all the information about a new datasource. ##### Content | Field | Type | Content | | ----------------- | ---------------------------- | ------------------------------------------------------------ | | success | KismetDatasource.SubSuccess | Success report for `KDSOPENSOURCE` | | dlt | int32 | *Optional* DLT (data link type) for packets from this source | | capture_interface | string | *Optional* Capture interface, if different than the specified interface. This is common for Wi-Fi devices which use virtual interfaces for capturing. | | channels | KismetDatasource.SubChannels | *Optional* Supported channels | | channel | KismetDatasource.SubChanset | *Optional* Fixed channel if not hopping | | hop_config | KismetDatasource.SubChanhop | *Optional* Channel hopping information | | hardware | string | *Optional* Hardware / chipset | | message | KismetExternal.MsgbusMessage | *Optional* User message | | spectrum | KismetExternal.SubSpecset | *Optional* Spectrum options | | uuid | string | *Optional* Source UUID | | warning | string | *Optional* Warning message about datasource, which will be displayed in the datasource details | ##### Response *None* #### `KDSPROBESOURCE` (KismetDatasource.ProbeSource) *Kismet -> Datasource* Kismet will attempt to match a source to a datasource driver by asking each datasource to probe the source definition. ##### Content | Field | Type | Content | | ---------- | ------ | ------------------------ | | definition | string | Kismet source definition | ##### Response `KDSPROBESOURCEREPORT` KismetDatasource.ProbeSourceReport #### `KDSPROBESOURCEREPORT` (KismetDatasource.ProbeSourceReport) *Datasource -> Kismet* ##### Content | Field | Type | Content | | -------- | ---------------------------- | ------------------------------------ | | success | KismetDatasource.SubSuccess | Success report for `KDSPROBESOURCE` | | message | KismetExternal.MsgbusMessage | *Optional* User message | | channels | KismetDatasource.SubChannels | *Optional* Supported channels | | channel | KismetDatasource.SubChanset | *Optional* Fixed non-hopping channel | | spectrum | KismetDatasource.SubSpecset | *Optional* Spectral scanning support | | hardware | string | *Optional* Hardware / chipset | ##### Response *None* #### `KDSWARNINGREPORT` (KismetDatasource.WarningReport) *Datasource -> Kismet* `KDSWARNINGREPORT` can be used by the datasource to set a non-fatal warning condition; this will be shown in the datasource details. ##### Content | Field | Type | Content | | ------- | ------ | ------------------------------------------------------ | | warning | string | Warning message to be shown in the datasource details. | ##### Response *None* ### KDS Subcomponents When the same data is used in multiple packets, it is typically placed in a `KismetDatasource.Sub...` message which is included in the top-level command. Many `Sub...` blocks contain only a single field; these may be expanded in the future to contain multiple fields, depending on the requirements of the protocol. #### `KismetDatasource.SubBuffer` Some datasources may need to send a complete protobuf record for data; this can be accomplished with the SubBuffer structure, which contains simply: | Field | Type | Content | | --------- | ------ | ------------------------------------------- | | time_sec | uint64 | Timestamp of record, Posix second precision | | time_usec | uint64 | Timestamp of record, microseconds | | type | string | Arbitrary buffer type to help decoder | | buffer | bytes | Packed protobuf buffer | #### `KismetDatasource.SubChannels` Basic list of channels. Channels are reported as strings, as they can represent complex tuning options (such as `6HT40+` for Wi-Fi). | Field | Type | Content | | -------- | -------- | ----------------- | | channels | string[] | Array of channels | #### `KismetDatasource.SubChannel` Basic channel. Channels are reported as strings, as they can represent complex tuning options. | Field | Type | Content | | ------- | ------ | ------- | | channel | string | Channel | #### `KismetDatasource.SubChanhop` | Field | Type | Content | | ------------ | -------- | ------------------------------------------------------------ | | channels | string[] | Array of channels to configure as the hopping pattern | | rate | double | *Optional* Rate at which to hop, in hops per second. Hop rates less than 1 result in dwelling on a channel for longer than a second. | | shuffle | bool | *Optional* Automatically shuffle the hop list to minimize frequency overlap (maximizing channel coverage). | | shuffle_skip | uint32 | *Optional* Skip interval when shuffling; this is typically calculated by Kismet to be a prime factor of the number of channels in the hop list, ensuring coverage. | | offset | uint32 | *Optional* Offset into the hopping channel list; this is typically calculated by Kismet when multiple radios are present on the same frequency band, and maximizes coverage. | #### `KismetDatasource.SubGps` | Field | Type | Content | | -------------- | ------ | ------------------------------------------------ | | lat | double | Latitude | | lon | double | Longitude | | alt | double | Altitude (meters) | | speed | double | Speed (kph) | | heading | double | Heading (degrees) | | precision | double | Location precision (meters) | | fix | uint32 | GPS fix quality (2 = 2d, 3 = 3d) | | time_sec | uint64 | GPS position timestamp as Posix second precision | | time_usec | uint64 | GPS position timestamp as microsecond precision | | type | string | GPS type (As defined by GPS driver) | | name | string | GPS name (As defined by user) | | high_prec_time | double | *Optional* High-precision second+nanosecond time | #### `KisDatasource.SubJson` | Field | Type | Content | | --------- | ------ | ------------------------------------------- | | time_sec | uint64 | Message timestamp as Posix second precision | | time_usec | uint64 | Message timestamp as microsecond precision | | type | string | Message type to assist in parsing | | json | string | Message, in JSON | #### `KisDatasource.SubInterface` | Field | Type | Content | | --------- | ------ | ------------------------------------------------------------ | | interface | string | Supported interface (which can be passed via `-c [interface]` in Kismet for example) | | flags | string | Required option flags (which will be passed via `-c [interface]:flags` in Kismet for example); flags can refine the interface parameters, etc. | | hardware | string | *Optional* Hardware / chipset of device | #### `KisDatasource.SubPacket` Raw packet data is injected into the Kismet Packetchain system. Datasources which send data with a DLT handled by Kismet will be automatically processed; datasources sending a new DLT will have to provide a parser for that link type. | Field | Type | Content | | --------- | ------- | ------------------------------------------------------------ | | time_sec | uint64 | Packet timestamp as Posix second precision | | time_usec | uint64 | Packet timestamp microsecond precision | | dlt | uint32 | DLT (Data Link Type) of packet content, as returned by libpcap | | size | uint64 | Packet payload size | | data | bytes[] | Raw packet data | #### `KisDatasource.SubSignal` Some packet formats include signal-level data as part of the packet headers (for example, Radiotap); for other packets, this data may be available as an external set of data. | Field | Type | Content | | ----------- | ------ | ------------------------------------------------------------ | | signal_dbm | double | *Optional* Signal level in dBm | | noise_dbm | double | *Optional* Noise level in dBm | | signal_rssi | double | *Optional* Signal level in RSSI. Kismet cannot convert RSSI to a meaningful number, so whenever possible, a datasource should prefer dBm) | | noise_rssi | double | *Optional* Noise level in RSSI. Kismet cannot convert RSSI to a meaningful number, so whenever possible, a datasource should prefer dBm) | | freq_khz | double | *Optional* Frequency of packet, in kHz | | channel | string | *Optional* Channel of packet, as a string meaningful to the datasource type | | datarate | double | *Optional* Data rate of packet | #### `KisDatasource.SubSpecSet` For data sources which support raw spectrum capture, the `SubSpecSet` configuration block will be sent to configure the ranges. | Field | Type | Content | | ------------------ | ------ | ------------------------------------------------------------ | | start_mhz | double | *Optional* Starting frequency of sample sweep, in MHz | | end_mhz | double | *Optional* Ending frequency of sample sweep, in MHz | | samples_per_bucket | double | *Optional* Number of samples taken per frequency bucket | | bucket_width_hz | double | *Optional* Width of sample bucket, in Hz | | enable_amp | bool | *Optional* If available, enable amplifier in radio | | if_amp | uint64 | *Optional* If available, amplification at the IF stage | | baseband_amp | uint64 | *Optional* If available, amplification at the baseband stage | #### `KisDatasource.SubSpectrum` Data sources which support raw spectrum capture return the spectrum record in a `SubSpectrum`. | Field | Type | Content | | --------------- | -------- | -------------------------------------------------------- | | time_sec | uint64 | *Optional* Timestamp of sweep, as Posix second precision | | time_usec | uint64 | *Optional* Timestamp of sweep, microsecond precision | | start_mhz | double | *Optional* Starting frequency of sweep, in MHz | | end_mhz | double | *Optional* Ending frequency of sweep, in MHz | | bucket_width_hz | double | *Optional* Width of sample buckets | | data | uint32[] | *Optional* Sweep samples | #### `KisDatasource.SubSuccess` Response messages include a `SubSuccess`; this is used to indicate command completion. | Field | Type | Content | | ------- | ------ | ------------------------------------------------------------ | | success | bool | Transaction was successful (or not) | | seqno | uint32 | Sequence number of command we are responding to. If this is a runtime error not associated with a specific command, this may be 0. | ## Defining the driver: Deriving from KisDatasource The datasource driver is the C++ component which brokers interactions between the capture binary and Kismet. All datasources are derived from `KisDatasource`. A KisDatasource is based on a `tracker_component` to provide easy export of capture status. The amount of customization required when writing a KisDatasource driver depends on the amount of custom data being passed over the IPC channel. For packet-based data sources, there should be little additional customization required, however sources which pass complex pre-parsed objects will need to customize the protocol-handling methods. KisDatasource instances are used in two ways: 1. *Maintenance* instances are used as factories to create new instances. A maintenance instance is used to enumerate supported capture types, initiate probes to find a type automatically, and to build a capture instance. 2. *Capture* instances are bound to an IPC process for the duration of capture and are used to process the full capture protocol. At a minimum, new datasources must implement the following from KisDatasource: *probe_type(...)* is called to find out if this datasource supports a known type. A datasource should return `true` for each type name supported. ```C++ virtual bool probe_type(string in_type) { if (StrLower(in_type) == "customfoo") return true; return false; } ``` *build_data_source()* is the factory method used for returning an instance of the KisDatasource. A datasource should simply return a new instance of its custom type. ```C++ virtual KisDataSource *build_data_source() { return new CustomKisDataSource(globalreg); } ``` A datasource which operates by passing packets should be able to function with no further customization: Packet data passed via the `PACKET` record will be decapsulated and inserted into the packetchain with the proper DLT. ## Handling the PHY Kismet defines `PhyHandler` objects to handle different physical layer types - for example there are phyhandlers for IEEE802.11, Bluetooth, and so on. A phy handler is responsible for defining any custom data structures specific to that phy, converting phy-specific data to the common interface so that Kismet can make generic devices for it, providing any additional javascript and web resources, and similar tasks. ## Defining the PHY Phy handlers are derived from the base `Kis_Phy_Handler` class. At a minumum a new phy must provide (and override): * The basic C++ contructor and destructor implementations * The create function to build an actual instance of the phy handler * A common classifier stage to create common info from the custom packet info * A storage loader function to attach any custom data when a device is loaded from storage ## Loading from storage and custom data types A new phy will almost certainly define a custom tracked data type - `dot11_tracked_device` and `bluetooth_tracked_device` for instance. As part of defining this custom type, the phy must provide a storage loader function to import stored data into a proper object. In addition, there are some specific pitfalls when loading custom objects - be sure to check the "Restoring vector and map objects" section of of the `tracked_component` docs! ## Handling the DLT A datasource which is packet-based but does not conform to an existing DLT defined in Kismet will often need to provide its own DLT handler. ### Do I need a custom DLT handler? If data records are entirely parsed by the classifier (see below for more information), then a separate DLT handler may not be necessary, however if your DLT embeds signal, location, or other information which needs to be made available to other Kismet data handlers, it should be decoded by your DLT handler. Capture sources implementing alternate capture methods for known DLTs (for instance, support for 802.11 on other operating systems, etc.) do not need to implement a new DLT handler. ### Deriving the DLT Kismet DLT handlers are derived from `Kis_DLT_Handler` from `kis_dlt.h`. A DLT handler needs to override the constructor and the `HandlePacket(...)` functions: ```C++ class DLT_Example : public Kis_DLT_Handler { public: DLT_Example(GlobalRegistry *in_globalreg); virtual int HandlePacket(kis_packet *in_pack); }; DLT_Example::DLT_Example(GlobalRegistry *in_globalreg) : Kis_DLT_Handler(in_globalreg) { /* Packet components and insertion into the packetchain is handled automatically by the Kis_DLT_Handler constructor. All that needs to happen here is setting the name and DLT type */ dlt_name = "Example DLT"; /* DLT type is set in tcpdump.h */ dlt = DLT_SOME_EXAMPLE; /* Optionally, announce that we're loaded */ _MSG("Registering support for DLT_SOME_EXAMPLE", MSGFLAG_INFO); } /* HandlePacket(...) is called by the packet chain with the packet data as reported by the datasource. This may already include GPS and signal information, as well as the actual link data frame. HandlePacket is responsible for decapsulating the DLT, creating any additional kis_packet records, and prepping the data for the classifier stage. */ int DLT_Example::HandlePacket(kis_packet *in_pack) { /* Example sanity check - do we already have packet data decapsulated? For a type like radiotap or PPI that encodes another DLT, this encapsulated chunk might be handled differently */ kis_datachunk *decapchunk = (kis_datachunk *) in_pack->fetch(pack_comp_decap); if (decapchunk != NULL) { return 1; } /* Get the linklayer data record */ kis_datachunk *linkdata = (kis_datachunk *) in_pack->fetch(pack_comp_linkframe); /* Sanity check - do we even have a link chunk? */ if (linkdata == NULL) { return 1; } /* Sanity check - does the DLT match? */ if (linkdata->dlt != dlt) { return 1; } /* Other code goes here */ } ``` ## Handling Non-Packet Data Non-packet data can be decapsulated by extending the `KisDataSource::handle_packet` method. By default this method handles defined packet types; an extended version should first call the parent instance. ```C++ void SomeDataSource::handle_packet(string in_type, KVmap in_kvmap) { KisDataSource::handle_packet(in_type, in_kvmap); string ltype = StrLower(in_type); if (ltype == "customtype") { handle_packet_custom(in_kvmap); } } ``` Extended information can be added to a packet as a custom record and transmitted via the Kismet packetchain, or can be injected directly into the tracker for the new phy type (See the [datatracker](/docs/dev/datatracker.html) docs for more information). Injecting into the packet chain allows existing Kismet code to track signal levels, location, etc., automatically. If the incoming data is directly injected into the data tracking system for the new phy type, then special care must be taken to create pseudo-packet records for the core device-tracking system. Ultimately, a pseudo-packet event must be created, either when processing the custom IPC packet or in the device classifier. Generally, it is recommended that a datasource attach the custom record to a packet object and process it via the packetchain as documented in [datatracker](/docs/dev/datatracker.html). When processing a custom frame, existing KV pair handlers can be used. For example: ```C++ void SomeDataSource::handle_packet_custom(KVmap in_kvpairs) { KVmap::iterator i; // We inject into the packetchain so we need to make a packet kis_packet *packet = NULL; // We accept signal and gps info in our custom IPC packet kis_layer1_packinfo *siginfo = NULL; kis_gps_packinfo *gpsinfo = NULL; // We accept messages, so process them using the existin message KV // handler if ((i = in_kvpairs.find("message")) != in_kvpairs.end()) { handle_kv_message(i->second); } // Generate a packet using the packetchain packet = packetchain->GeneratePacket(); // Gather signal data if we have any if ((i = in_kvpairs.find("signal")) != in_kvpairs.end()) { siginfo = handle_kv_signal(i->second); } // Gather GPS data if we have any if ((i = in_kvpairs.find("gps")) != in_kvpairs.end()) { gpsinfo = handle_kv_gps(i->second); } // Add them to the packet if (siginfo != NULL) { packet->insert(pack_comp_l1info, siginfo); } if (gpsinfo != NULL) { packet->insert(pack_comp_gps, gpsinfo); } // Gather whatever custom data we have and add it to the packet if ((i = in_kvpairs.find("customfoo")) != in_kvpairs.end()) { handle_kv_customfoo(i->second, packet); } // Update the last valid report time inc_num_reports(1); set_last_report_time(globalreg->timestamp.tv_sec); // Inject the packet into the packet chain, this will clean up // the packet when it's done with it automatically. packetchain->ProcessPacket(packet); } ``` kismet-docs-master/devel/datasource_capframework.md000066400000000000000000000060741372362651600231270ustar00rootroot00000000000000--- title: "Datasource capframework library" permalink: /docs/devel/datasources_capframework/ toc: true docgroup: "devel-cpp" excerpt: "The datasource captureframework C API" --- ## Extending Kismet: Datasource Capture Framework Pure-C API Kismet supports capturing from any binary capable of talking a simple IPC/network protocol. To minimize the requirements and simplify embedding capture code in small embedded systems without a C++ runtime, `capture_framework.h` and `capture_framework.c` implement the protocol and main communications loops in a pure-c helper library. ## Pure-C Capture-Framework is written in pure-c which should be compatible with C99 and does not require any C++ runtimes. The Kismet plugins and decoders still require C++. ## Communication Kismet capture binaries communicate over IPC on a shared pipe, or via a TCP network connection to the Kismet server. When using piped IPC, the pipe pairs are passed to the exec()'d capture binary in the --in-fd and --out-fd command line options. Data is buffered in generic, simplistic ring buffer structures and dispatched via a standard select() loop. ## Threads Capture-Framework uses pthreads to spawn two threads, in addition to the primary main thread: ### Capture Thread The capture callback (more on these soon) is run in an independent, cancelable thread. This allows the capture calls on a binary to block without interfering with the standard select() loop and communication with the Kismet server. ### Channel Hopping Thread If channel hopping is enabled in the capture binary, an independent thread performs the timing and channel set commands. ## Callbacks All expandable functions in Capture-Framework are handled by passing callback functions; listing devices, probing, opening, setting channels, etc, are handled by callback functions and can be trivially customized. # Order of Operations Kismet will launch a capture binary and perform one of several actions: ## List devices This is called on all capture drivers to create a list of devices the user could pick. The capture binary is responsible for enumerating any devices it can support via any mechanism; for instance the Linux Wi-Fi capture binary enumerates devices by processing the /sys/class/net/ pseudofilesystem. After listing devices, a capture binary should go into a spindown/pending state and wait to be closed; no other action will be taken this execution. ## Probe definition This is called to determine the driver which can handle a definition, when no type is explicitly specified. The capture binary is responsible for determining if this looks like a source that can be opened. For example, the pcapfile capture will attempt to open the definition as a pcap; the Linux Wi-Fi capture will attempt to retrieve the interface channel via SIOCGIWCHAN to determine if it looks to be a Wi-Fi device. After returning a probe response, a capture binary should go into a spindown/pending state and wait to be closed; no other action will be taken this execution. ## Open definition This is called to actually open and begin capturing from an interface. kismet-docs-master/devel/datatracker.md000066400000000000000000000235271372362651600205230ustar00rootroot00000000000000--- title: "Extending device and data tracking" permalink: /docs/devel/data_types/ toc: true docgroup: "devel-cpp" excerpt: "Extending the Kismet C++ data classifier system." --- Once data has been captured (see the [datasource docs](/docs/dev/datasource.html) for more details about creating a data source) and handled by the DLT handler, additional processing can be done to create device records and data. Kismet stores information about a device in a `tracker_component` record held by the `DeviceTracker` class. For more information about the internals and how to make your own `tracker_component` check out the [tracked component docs](/docs/dev/tracked_component.html). Information stored in the common base element is used to show summaries about the devices seen, create statistics, and to show information about a device when no custom presentation is defined for the extra data. Kismet will automatically track signal and location information for the device, assuming they are provided, as well as peak signal locations, device names, packet counts, time ranges seen, channels and frequencies used, and similar information, so long as the phy handler makes the data available. ## The Common Classifier Each data source which defines a new phy layer (i.e., something not already handled in Kismet elsewhere) is responsible for reducing information from that phy to something the common layer of Kismet can understand. Device records are automatically created by Kismet using the `kis_common_info` packet record. Datasources need to provide some mechanism for turning their packets and data into a common record, and either attach that record to the packet chain, or explicitly notify the `DeviceTracker` system via a pseudo-packet. ### Common Info From Packets Typically, for a packet-based protocol, the information needed to form the common info for categorization is part of the packet. For example, in Wi-Fi, the device MAC, common encryption signifiers, data sizes, etc., are all encoded in the dot11 frame, they just need to be converted to the common type. `kis_common_info` is a basic packet component defined in `packet.h`, and contains a very simple representation of data Kismet needs to assemble a basic device: #### Mac Addresses (and Mac-Address-Like Addresses) Four main MAC addresses are recorded: ```C++ mac_addr source, dest; mac_addr transmitter, device; ``` * **source** - The original source of the packet. This may not be the address of the device that transmitted it, for example in Wi-Fi this could be the source MAC of a wired device bridged to wireless. * **dest** - The destination of the packet. This may or may not be a wireless device, for instance a packet transmitted from a wireless network via a bridge to a wired device. * **transmitter** - The address of the radio which transmitted the packet, if available. This may be the same as the source MAC. Again using Wi-Fi as an example, the transmitter MAC address would be the access point. * **device** - The actual address of the device. This is likely the same as the source MAC, and is the address used to identify the device. If the phy type you are implementing doesn't use traditional MAC addresses, a similar unique addressing scheme must be created for devices in that phy, which can be packed into a MAC-address style record. The addressing should be unique and repeatable (that is, the same device must generate the same MAC-like address to be tracked properly). #### Basic Type The basic type is aggregated per-packet and used to indicate the type of packet: ```C++ kis_packet_basictype type; ``` Which draws from the set of: ```C++ enum kis_packet_basictype { packet_basic_unknown = 0, packet_basic_mgmt = 1, packet_basic_data = 2, packet_basic_phy = 3 }; ``` * **unknown** - An unclassifiable generic packet * **mgmt** - Management / network maintenance packets. In Wi-Fi networks, management frames include beacons, probe requests, etc. * **data** - Packet carries data of some sort * **phy** - Physical-layer control packets. In Wi-Fi, CTS/RTS packets are classified as phy-type frames #### Basic Encryption Set The basic encryption allows Kismet to show encrypted, unencrypted, decrypted, and vulnerable devices. A phy should provide detailed information about the types of encryption used inside its own data, but this allows Kismet to display more common information. ```C++ // Encryption if applicable uint32_t basic_crypt_set; ``` Which is a bit-set of the following from `devicetracker.h`: ```C++ #define KIS_DEVICE_BASICCRYPT_NONE 0 #define KIS_DEVICE_BASICCRYPT_ENCRYPTED (1 << 1) #define KIS_DEVICE_BASICCRYPT_L2 (1 << 2) #define KIS_DEVICE_BASICCRYPT_L3 (1 << 3) #define KIS_DEVICE_BASICCRYPT_WEAKCRYPT (1 << 4) #define KIS_DEVICE_BASICCRYPT_DECRYPTED (1 << 5) ``` * **NONE** and **ENCRYPTED** define basic encryption being present (or not). * If available, **L2** and **L3** may be used to indicate layer 2 (such as WPA on Wi-Fi) or layer 3 (such as a VPN detected in layer 3 traffic). * **WEAKCRYPT** is used to indicate that the encryption method is known to be vulnerable, for example WEP on Wi-Fi is flagged as WEAKCRYPT. This can be used by Kismet to identify devices which are at increased risk. * **DECRYPTED** indicates that the data is encrypted, but has been decrypted - for example via a known WEP key or other decryption. #### Additional Data ```C+++ int phyid; ``` The phy id should be filled in with the ID of the phy type registered with Kismet. ```C++ int error; ``` A boolean value indicating the packet is in error. Kismet uses this to track error rates on tracked devices. ```C++ int datasize; ``` Basic data size in bytes, used by Kismet to calculate the aggregate data of the tracked device. ```C++ string channel; ``` Phy-specific complex channel. Channel is represented as a string and can carry special attributes, or can be a frequency representation if the phy has no channel definitions. For instance, for 802.11N Wi-Fi, a channel may be represented as "6HT40+" while a simpler radio protocol may simply use "433.9MHz" as the channel string. ```C++ double freq_khz; ``` The center frequency of the communication, in kHz. ### An Example of Common Info To demonstrate how to use the common into, lets take the 802.11 common classifier as an example. This is registered by the 802.11 decoder as a packet chain element in the `CLASSIFIER` portion. The classifier is called after we have already: 1. Decapsulated the 802.11 frame from any L2 data (such as radiotap or PPI) 2. Processed the signalling (and in PPI's case, location) data from the L2 header 3. Processed the 802.11 packet into our own packet component, dot11info, which tells us about the 802.11 addressing, encryption, errors, etc. Already knowing the 802.11 characteristics makes filling in the `kis_common_info` record very simple. ```C++ int Kis_80211_Phy::CommonClassifierDot11(CHAINCALL_PARMS) { /* Grab the instance of the Dot111 Phy from the auxptr, remember we're a static function so that we can be called directly */ Kis_80211_Phy *d11phy = (Kis_80211_Phy *) auxdata; /* Get the 802.11 component of the packet, or die trying */ dot11_packinfo *dot11info = (dot11_packinfo *) in_pack->fetch(d11phy->pack_comp_80211); if (dot11info == NULL) return 0; /* Get the common info, and if it doesn't exist, make one and insert it. There shouldn't be a situation where we have a CI already, but if we just inserted blindly we risk leaking memory. */ kis_common_info *ci = (kis_common_info *) in_pack->fetch(d11phy->pack_comp_common); if (ci == NULL) { ci = new kis_common_info; in_pack->insert(d11phy->pack_comp_common, ci); } /* Set the phy ID from our phyhandler */ ci->phyid = d11phy->phyid; /* Start decoding the dot11 to get our common info */ if (dot11info->type == packet_management) { ci->type = packet_basic_mgmt; if (dot11info->source_mac == globalreg->empty_mac) { if (dot11info->bssid_mac == globalreg->empty_mac) { ci->error = 1; } ci->device = dot11info->bssid_mac; } else { ci->device = dot11info->source_mac; } ci->source = dot11info->source_mac; ci->dest = dot11info->dest_mac; ci->transmitter = dot11info->bssid_mac; } else if (dot11info->type == packet_phy) { // ... } else if (dot11info->type == packet_data) { // ... } /* If we're known corrupt from the dot11 handlers... */ if (dot11info->type == packet_noise || dot11info->corrupt || in_pack->error || dot11info->type == packet_unknown || dot11info->subtype == packet_sub_unknown) { ci->error = 1; } /* Set the channel from the dot11 channel */ ci->channel = dot11info->channel; /* Set the data size */ ci->datasize = dot11info->datasize; /* Either we're encrypted or we're not */ if (dot11info->cryptset == crypt_none) { ci->basic_crypt_set = KIS_DEVICE_BASICCRYPT_NONE; } else { ci->basic_crypt_set = KIS_DEVICE_BASICCRYPT_ENCRYPTED; } /* Add in the additional L2/L3 crypto knowledge from the 802.11 decoder */ if (dot11info->cryptset & crypt_l2_mask) { ci->basic_crypt_set |= KIS_DEVICE_BASICCRYPT_L2; } if (dot11info->cryptset & crypt_l3_mask) { ci->basic_crypt_set |= KIS_DEVICE_BASICCRYPT_L3; } return 1; } ``` ## Custom Device Data All but the most basic of device records will need custom device data. Because the `kis_tracked_base` record is a `tracker_component` record, it can hold arbitrary additional `tracker_component` data. These sub-elements will automatically be included in serialization to web clients and other exports. Data can be included either as multiple unique fields inserted into the `kis_tracked_base` record, or as a complete sub-record containing all the information. For organization and simplicity (and ease of serialization to formats like XML) it is generally much better to create a complete sub-record and attach it to the `kis_tracked_base`. kismet-docs-master/devel/helper_interface.md000066400000000000000000000264451372362651600215370ustar00rootroot00000000000000--- title: "Helper tools" permalink: /docs/devel/external_helper_tools/ toc: true docgroup: "devel-cpp" excerpt: "The Kismet external tool API defines how Kismet talks to capture and helper binaries." --- Kismet helper tools are external programs which Kismet uses; splitting functionality into an external helper can be for several reasons: 1. Security. By moving operations into external tools, Kismet can avoid requiring root / administrative privileges itself. Almost any capture from a network interface will require root, both to configure the interface and to initiate the packet capture. 2. Enabling other languages. Kismet is written in C++, but this isn't necessarily the best language for all situations. Kismet uses pure C for capture tools to minimize the runtime library requirements, and other components may best be implemented in a language like Python. 3. Plugin functionality. Some plugins need to manage long running tools, or the author may wish to avoid C++ for whatever reason. 4. Process management. Some plugins and capture methods demand their own lifecycle loops. While it would likely be possible to encapsulate these in a thread, using process separation ensures no crossover problems. ## External Interface Protocol Kismet uses a flexible protocol to communicate with external tools. Built around Google Protobuf, each top-level message is bundled in a network frame for delivery, and contains: 1. The command type; an arbitrary string which defines the type, such as "MESSAGE" or "CONFIGURE". 2. A unique sequence number, which is used to respond to commands or return errors. 3. The payload of the command, as a string. The payload should typically be a Protobuf serialized message. While, technically, a custom command could encode any data, implementations are strongly encouraged to use the Protobuf framework. ## KismetExternal Commands The top-level protocol defines a few key commands and their payloads: ### `MESSAGE` (KismetExternal.MsgbusMessage) *Helper -> Kismet* Prints a message via the MessageBus system; these messages are printed to the Kismet console, displayed in the Messages section of the UI, and logged to the Messages section of the Kismet log. #### Content | Field | Type | Content | | ------- | ----------- | ----------------------------------------- | | msgtype | MessageType | Type of message (Info, Debug, Alert, Etc.) | | msgtext | string | Message content | #### MessageType | Type | Value | | ----- | ----- | | DEBUG | 1 | | INFO | 2 | | ERROR | 4 | | ALERT | 8 | | FATAL | 16 | ### `PING` (KismetExternal.Ping) *Bidirectional* A ping message acts as a keepalive signal which expects an answering `PONG` packet. #### Content *None* ### `PONG` (KismetExternal.Pong) *Bidirectional* Answering packet to a `PING`, which must include the sequence number of the `PING` command. `PONG` responses should be sent immediately. #### Content | Field | Type | Content | | ---------- | ------ | ------------------------------------------ | | ping_seqno | uint32 | Seqno of `PING` request this is a reply to | ### `SHUTDOWN` (KismetExternal.Shutdown) *Bidirectional* Either side of the connection can request the connection be shut down; upon receiving a `SHUTDOWN` message the external helper will be terminated. #### Content *None* ### `SYSTEMREGISTER` (KismetExternal.SystemRegister) *Helper -> Kismet* When using network sockets to connect external helpers, the Kismet listening socket may be multiplexed across many different handlers. The external helper can identify itself with the `SYSTEMREGISTER` message so that it may be dispatched to the proper handler. #### Content | Field | Type | Content | | --------- | ------ | -------------- | | subsystem | string | Subsystem name | ## KismetExternal Eventbus Proxy *Added 2020-07* Kismet implements a serializable eventbus internally to pass messages among disparate parts of the codebase and to provide an event-based API. Events include phy layer handler creation, datasource status, new device creation, and more. A kismetexternal tool may subscribe to the eventbus, and publish basic events. ### `EVENTBUSREGISTER` (KismetEventbus.EventbusRegister) *Helper -> Kismet* To receive events, a tool must register with Kismet. Events may be specified as specific events, or `"*"` for all events. #### Content | Field | Type | Content | | ----- |----- | ------- | | event | string[] | Repeating list of events to subscribe to | ### `EVENTBUSPUBLISH` (KismetEventbus.EventbusPublishEvent) *Helper -> Kismet* Tools may publish *basic* eventbus events. These events should not overlap with existing Kismet events, and may only contain JSON content. This content will not be turned into complex C++ objects inside Kismet, but will be available to C++ code as a JSON structure. Content published will be inserted into the event content under the key `'kismet.eventbus.event_json'`. | Field | Type | Content | | -- | -- | -- | | event_type | string | Event type / name | | event_content | string | Event JSON content which will be inserted into the `kismet.eventbus.event_json` key in the event. | ## KismetExternal HTTP Proxy The Kismet external protocol has hooks for extending the web server functionality to external tools, regardless of the language they are written in. ### `HTTPREQUESTAUTH` (KismetExternalHttp.HttpAuthTokenRequest) *Helper -> Kismet* External tools may request a HTTP authorization token; instead of transmitting the Kismet admin username and password, a web session cookie is generated and returned in a `HTTPAUTH` response. #### Content *None* ### `HTTPAUTH` (KismetExternalHttp.HttpAuthToken) *Kismet -> Helper* Once Kismet has generated a HTTP authentication token it is sent to the helper in a `HTTPAUTH` response. The session hash is suitable for use as the `KISMET` cookie in HTTP communication. #### Content | Field | Type | Content | | ----- | ------ | --------------- | | token | string | HTTP auth token | ### `HTTPREGISTERURI` (KismetExternalHttp.HttpRegisterUri) *Helper -> Kismet* A helper can create endpoints in the Kismet server by registering the URI. The URI can be registered as a GET or PUSH, and can specify if there just be an authenticated login. Kismet will handle the incoming web request and authentication validation. #### Content | Field | Type | Content | | ------------- | ------- | -------------------------------------------------- | | uri | string | Full path and file extension URI to register | | method | string | HTTP method (currently GET and POST are supported) | ##### Deprecated | Field | Type | Content | | auth_required | boolean | Indicates if a valid HTTP session is required | As of `2019-04-git` Kismet requires authentication for all API calls, and this parameter is now ignored. ### `HTTPREQUESTCANCEL` (KismetExternalHttp.HttpRequestCancel) *Kismet->Helper* If a HTTP request is closed by the client before the external helper has sent a `HTTPRESPONSE` message with `close_connection`, Kismet will send a `HTTPREQUESTCANCEL` to the helper. The helper should stop processing this request. #### Content | Field | Type | Message | | ------ | ------ | -------------------------- | | req_id | uint32 | Session ID to be cancelled | ### `HTTPREQUEST` (KismetExternalHttp.HttpRequest) *Kismet -> Helper* When an incoming request is received by the web server which matches a registered URI, Kismet will send a request packet to the helper with a unique connection ID and any form post variables. If the URI requires a login, Kismet will only send the `HTTPREQUEST` to the helper tool if there is a valid login session. #### Content | Field | Type | Content | | --------- | --------------- | ------------------------------------------------------------ | | req_id | uint32 | Unique request ID, `HTTPRESPONSE` commands must reference this ID | | uri | string | Full path and file extension of the URI | | method | string | HTTP method | | post_data | SubHttpPostData | *Optional* Array of HTTP Post variables | #### `SubHttpPostData` (KismetExternalHttp.SubHttpPostData) HTTP POST variables are transmitted as an array of HttpPostData. | Field | Type | Content | | ------- | ------ | --------------------- | | field | string | POST variable field | | content | string | POST variable content | ### `HTTPRESPONSE` (KismetExternalHttp.HttpResponse) *Helper -> Kismet* Multiple response frames may be sent for any request; request responses may include custom HTTP headers, fixed content or streaming data, and external helpers may keep the connection open in a streaming mode to continually send streaming real-time data. Internally, the web proxy system uses the Kismet chained buffer system; this sends the buffer to the web client as quickly as possible while it is still being populated; if the client is fast enough, the buffer will never grow beyond the basic size, but if the client is not keeping up with the buffer, it will grow automatically. The external tool can pass data as quickly as it can be generated without concern for the web budgeting system. Generally, an external tool should limit the data per frame to a reasonable amount (1kB would be a reasonable size); if a packet is larger than the buffer allocated in Kismet it will not be properly received and Kismet may be running on an extremely memory-constrained system. Large amounts of data can be sent by sending multiple response frames. The helper may include additional data in the `HTTPRESPONSE` such as custom HTTP headers, and the helper may change the HTTP result code. Headers may only be sent *before* or *with* the first `HTTPRESPONSE` message. #### Content | Field | Type | Content | | -------------- | ------------- | ------------------------------------------------------------ | | req_id | uint32 | Unique session ID (from `HTTPREQUEST`) | | header_content | SubHttpHeader | *Optional* Array of custom headers to send. May *only* be sent with the *first* `HTTPRESPONSE` message. | | content | bytes | *Optional* HTTP content. Messages should be limited to `1024` bytes of content; larger responses may be split over multiple `HTTPRESPONSE` messages. | | resultcode | uint32 | *Optional* HTTP numeric result code. Connections closed with no `HTTPRESPONSE` messages including a resultcode are closed with `200 OK` | | close_response | boolean | *Optional* This is the last `HTTPRESPONSE` message for this connection, close the HTTP request. If a `resultcode` has been provided, the final result of the request will be set accordingly. | #### `SubHttpHeader` (KismetExternalHttp.SubHttpHeader) HTTP header values to be transmitted at the beginning of the connection. | Field | Type | Content | | ------- | ------ | -------------- | | header | string | HTTP header | | content | string | Header content | kismet-docs-master/devel/log_kismet.md000066400000000000000000000344241372362651600203710ustar00rootroot00000000000000--- title: "Kismetdb logs" permalink: /docs/devel/kismetdb/ toc: true docgroup: "devel" excerpt: "The kismetdb log file is the new unified system for storing data, state, snapshots, devices, and all other info in Kismet." --- These docs represent a logfile which is under current development; until the first full release is done, the contents of the Kismet log are subject to change as corner cases are found. ## Kismet Log File The Kismet log file contains all the information gathered by Kismet about devices, supported phy types, packets, GPS coordinates during logging, and similar. Under previous versions of Kismet, this data could be found in disparate logs such as gpsxml, netxml, nettxt, and pcap. ## Internal Log Structure The Kismet log file is stored as a SQLite3 database, however it is not designed as a traditional strictly normalized database. In order to support the arbitrary data collected by Kismet about different phy layers and any Kismet plugins that may have been loaded, the Kismet log contains basic normalized fields such as location, timestamp, and device keys, but the majority of the data is stored as a serialized JSON object or as binary packet data. This means that basic queries (time, signal levels, location, device identifiers, and MAC addresses) can be done via SQL queries, but more complex queries will require retrieving the JSON object. ## Log Versions The log file version is stored in the `db_version` field of the `KISMET` table. When changes to the base database structure are made, this version will be incremented. ### Version 6 As of May 2019, Kismet has started using db_version 6. This version contains one change: 1. the `packets` table now has an additional field, `tags`. This is a space-separated list of arbitrary packet tags. These can be used to identify packets tagged by parts of the Kismet code, for instance, WPA handshake packets. ### Version 5 As of February 2019, Kismet has started using db_version 5. This version contains two major changes: 1. Kismet no longer stores GPS coordinates as normalized integers. GPS related data will be stored as SQL type `REAL`, an 8-byte double-precision float. 2. Kismet now adds per-packet GPS speed, altitude, and heading records. ### Version 4 Through Kismet 2018/2019 Beta 2, Kismet used db_version 4. This version *did not* contain per-packet altitude, speed, or heading records, and *did* contain normalized GPS coordinates. ## Data Formats The Kismet log uses a few consistent formats for data: ### Timestamps Timestamps are stored as integer seconds since the epoch for low-precision timestamps, and integer seconds since the epoch plus a second field of milliseconds for high-precision timestamps. This format matches the unix timestamp tv_sec and tv_usec format. ### GPS *As of KismetDB version 5* the GPS coordinates are stored as 8-byte `REAL` double-precision floats; these are the native GPS coordinate, and no transformation is necessary. *Prior to database version 5* the GPS coordinates were normalized to integers. #### *This is deprecated for all logs created under version 5 or newer*. Latitude and Longitude are normalized to a 6-digit precision integer using the conversion: *normalized_coord = (coordinate * 100000)* Coordinates can be automatically converted in SQL queries by using `/`: ```sql SELECT (lat / 100000.0), (lon / 100000) FROM ... ``` Be sure to specify a floating-point divisor (100000.0), otherwise the result will be converted to an integer. ### GPS Bounding and Average Coordinates GPS bounding coordinates are stored as 4 values, the minimum extreme latitude and longitude, and the maximum extreme latitude and longitude. These values define a bounding box which encloses all instances where a device was seen. The GPS average location is calculated by Kismet as a running average of all packets; this can be the least precise method of isolating the location of a device because it can be heavily influenced by the sampling pattern. For more precise location calculations, post-processing of the GPS records in the `PACKET` or `DATA` tables will yield better results. ### Device Keys Device keys are used to uniquely identify a device; the device key is used by Kismet as the indexing value for every device record, and incorporates the unique Kismet server which saw the device, the phy layer driver which processed the device, and the device-specific unique identifier (often the MAC address but not always). Internally, keys are represented as 128-bit numbers; in the Kismet log they are represented as a TEXT field and each device key will be unique. ### UUIDs UUIDs, or universally unique identifiers, are used in Kismet to identify specific instances of some long-living objects such as the Kismet server itself and data sources. UUIDs are stored in the Kismet log as a TEXT blob of the UUID string. ## Log Sections The Kismet log is divided into multiple sections (stored internally as SQLite3 tables). ### Alerts The `alerts` section holds records of Kismet IDS alerts. | Field | Type | Description | | ------- | ------------: | ------------------------------------------------------ | | ts_sec | *timestamp* | Alert timestamp, as second-precision timestamp integer | | ts_usec | *timestamp* | Alert timestamp as usec-precision timestamp integer | | phyname | *text* | Related phy name | | devmac | *text* | Primary related device MAC address | | lat | *real/double* | GPS latitude | | lon | *real/double* | GPS longitude | | header | *text* | Alert header / type | | json | *json* | Full alert content as JSON object | ### Data The `data` section holds arbitrary data records which are *not* packets but which have temporal or locational meaning; typically these will be generated by non-packet-based data sources such as the `sdr-rtl433` source which detects device events but does not supply the raw original bytes. | Field | Type | Description | | ---------- | ------------: | ------------------------------------------------------ | | ts_sec | *timestamp* | Event timestamp, as second-precision timestamp integer | | ts_usec | *timestamp* | Event timestamp, as usec-precision timestamp integer | | phyname | *text* | Capturing device phy name | | devmac | *text* | Captured device MAC, if any | | lat | *real/double* | GPS latitude | | lon | *real/double* | GPS longitude | | alt | *real/double* | GPS altitude, since database version 5 | | speed | *real/double* | GPS speed, since database version 5 | | heading | *real/double* | GPS heading, since database version 5 | | datasource | *uuid* | UUID of capturing datasource, as text | | type | *text* | Type of data record, as text | | json | *json* | Arbitrary JSON record of event | ### Datasource The `datasource` section holds up-to-date information about the datasources Kismet is capturing from; a datasource supplies information to Kismet and can be local, remote, packet-based, or event-based. | Field | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | | uuid | *uuid* | UUID of datasource | | typestring | *text* | Datasource type (such as `linuxwifi`) | | definition | *text* | Full source definition as passed in the `source=` config or the `-c ...` command-line option | | name | *text* | Source name | | interface | *text* | Capture interface (such as `wlan0`) | | json | *json* | Full device state (packet RRD, messages, etc) as JSON blob | ### Devices The `device` section holds complete Kismet device objects; the device object is encoded as a JSON object and contains all phy-related data and all tracked notes, data, and any other information about the device. | Field | Type | Description | | ---------------- | ------------: | ------------------------------------------------------------ | | first_time | *timestamp* | First time seen, as second-precision timestamp | | last_time | *timestamp* | Last time see, as second-precision timestamp | | devkey | *text* | Unique device key | | phyname | *text* | Name of primary phy (such as IEEE80211) | | devmac | *mac, text* | Device MAC (such as the source MAC address in IEEE80211) | | strongest_signal | *integer* | Strongest recorded signal during lifetime of device, typically in dBm but phy-specific | | min_lat | *real/double* | GPS bounding rectangle, minimum latitude | | min_lon | *real/double* | GPS bounding rectangle, minimum longitude | | max_lat | *real/double* | GPS bounding rectangle, maximum latitude | | max_lon | *real/double* | GPS bounding rectangle, maximum longitude | | avg_lat | *real/double* | GPS running average latitude | | avg_lon | *real/double* | GPS average running longitude | | bytes_data | *integer* | Number of bytes of data seen related to this device | | type | *text* | Phy-specific human-readable type, dependent on the phy | | device | *json* | Full JSON export of the device record and all enclosed fields | ### Messages The `messages` section holds text messages from Kismet; typically printed to the 'Messages' section of the UI or to the console. | Field | Type | Description | | ------- | ------------: | --------------------------------------------------------- | | ts_sec | *timestamp* | Message time, as second-precision integer | | lat | *real/double* | GPS latitude | | lon | *real/double* | GPS longitude | | alt | *real/double* | GPS altitude, since database version 5 | | speed | *real/double* | GPS speed, since database version 5 | | heading | *real/double* | GPS heading, since database version 5 | | msgtype | *text* | Message type/category (`INFO`, `ERROR`, `ALERT`, `FATAL`) | | message | *text* | Arbitrary message as printed by Kismet | ### Packets The `packets` section holds raw binary packets; packets can be of any DLT (data link type) supported by Kismet, and are tagged with per-packet GPS location (when available). The `packets` section is directly analogous to a pcap (or pcap-ng) file and can be directly converted to those formats with tools found in `log_tools/` in the Kismet directory. Packets are stored in the raw, original capture format; in the case of Wi-Fi this may be a format such as Radiotap which, itself, also encodes the frequency, signal levels, and detailed antenna data. Kismet exposes a normalized subset of per-packet data to facilitate slicing the Kismet log into manageable pieces easily. | Field | Type | Description | | ---------- | ------------: | ------------------------------------------------------------ | | ts_sec | *timestamp* | Packet time, as second-precision integer | | ts_usec | *timestamp* | Packet time, as usec-precision integer | | phyname | *text* | Name of capturing phy | | sourcemac | *text* | MAC address of packet source (if available) | | destmac | *text* | MAC address of packet destination (if available) | | transmac | *text* | MAC address of packet transmitter (if available) | | frequency | *real* | Decimal frequency of packet, in KHz (if available) | | devkey | *text* | Unique Kismet device key associated with this packet (if available) | | lat | *real/double* | GPS latitude | | lon | *real/double* | GPS longitude | | packet_len | *integer* | Total packet length, in bytes | | signal | *integer* | Received signal level of packet (typically in DBm but may be phy-specific) | | datasource | *uuid* | UUID of capturing Kismet data source, as string | | dlt | *int* | DLT (Data Link Type) of packet content; this correlates to the original packet format as understood by pcap (such as raw 802.11, radiotap, raw btle, and so on) | | packet | *blob* | Raw binary packet content | | error | *int* | Boolean, packet was flagged by Kismet as an error in rx or otherwise invalid due to parsing errors | | tags | *text* | Arbitrary space-separated list of tags added by packet dissectors in Kismet | ### Snapshots The `snapshots` section holds arbitrary time-based snapshots of data; this functions as a catch-all for Kismet plugins and other temporal data. | Field | Type | Description | | -------- | ------------: | ------------------------------------------ | | ts_sec | *timestamp* | Snapshot time, as second-precision integer | | ts_usec | *timestamp* | Snapshot time, as usec-precision integer | | lat | *real/double* | GPS latitude | | lon | *real/double* | GPS longitude | | snaptype | *text* | Snapshot record type | | json | *json* | Snapshot record, as JSON object | ## REST API If the Kismet Databaselog is enabled, Kismet will expose an API for extracting historic data. If the databaselog is not enabled, these APIs will not be available and will return an error. The `kismetdb` REST API [can be found here.](/docs/devel/webui_rest/kismetdb/) kismet-docs-master/devel/plugin.md000066400000000000000000000067761372362651600175430ustar00rootroot00000000000000--- title: "Creating Kismet plugins" permalink: /docs/devel/plugins/ toc: true docgroup: "devel" excerpt: "Kismet plugins can change server behavior (via C++ plugins), interface behavior (via Javascript), or both" --- Kismet can load additional code dynamically at runtime in the form of a plugin. Plugins are a double-edged sword: In their current implementation, plugins are full first-class citizens in the Kismet ecosystem; a plugin can perform any action Kismet native code can perform, and are given a direct reference to the internal Kismet module system. ## Plugin code Plugins are shared objects (.so files) with pre-defined functions, HTML and Javascript code, or external binaries launched over IPC which communicate with the Kismet server. Plugins can combine all of these aspects. ## Plugin locations Plugins can be installed into one of two locations: * System-wide plugins are installed into `[datadir]/kismet/plugins/` where `[datadir]` is the parameter passed to `./configure --datadir=...`. It defaults to `/usr/local/`. * Per-user plugins are installed into the users home directory under `~/.kismet/plugins/` ## Plugin static web content Plugins are mapped into the Kismet webserver under `/plugin/[plugin-directory-name]/` path. Plugins can add arbitrary content in this directory, but it is strongly recommended that they follow the following convention: * `[prefix]/plugins/[name]/httpd/js/` - Javascript files * `[prefix]/plugins/[name]/httpd/css/` - CSS files To register a JS module for automatic loading (for instance, to interact with the normal Kismet web UI and add new tabs, details, etc), a plugin must either: * Register the module with with the `kis_httpd_registry::register_js(...)` system * Define a plugin manifest stored in `[prefix]/plugins/[name]/manifest.conf` ## Plugin external HTTP helpers An external HTTP helper plugin communicates with Kismet over the external API IPC channel. The binary is launched by Kismet. External API plugins can add new endpoints to the Kismet server and communicate with Kismet via the IPC channel and the Kismet web API. ## Plugin manifests The manifest file allows Kismet to automatically derive information about a plugin with no native code - this allows for simple HTTP-only plugins which enhance the web UI without requiring them to include compiled code to register the plugin. The manifest file should be placed in `[prefix]/plugins/[name]/manifest.conf`, and takes the form of a Kismet config file (name=value pairs): | Key | Content | | ---- | ------- | | name | Plugin name | | description | Plugin description | | author | Plugin author | | version | Plugin version | | object | plugin shared object file name | | httpexternal | external API tool binary name | | js | JS module and path as `module_name,/web/path/to/js`.| Example manifest: ``` name=Webplugin description=Trivial web-only plugin author=Joe Random version=1.0.0 js=new_web_module,/plugin/webplugin/js/new_web_module.js ``` Example manifest for plugin with C++ code: ``` name=Codeplugin description=Standard code-based plugin author=Joe Random version=1.0.0 object=kismet-codeplugin.so js=code_web_module,/plugin/codeplugin/js/code_web_module.js ``` Example manifest for plugin with an external binary: ``` name=ProxyDemo description=Demo of a plugin using the external API tool to create new endpoints author=Joe Random version=1.0.0 httpexternal=kismet_proxydemo js=proxied_web_module,/plugin/proxydemo/js/proxied_web_module.js ``` kismet-docs-master/devel/plugin_http_helper.md000066400000000000000000000313651372362651600221310ustar00rootroot00000000000000--- title: "Kismet External HTTP Helper Plugins" permalink: /docs/devel/dev/plugin_httphelper/ toc: true docgroup: "devel" excerpt: "Extending Kismet via external helpers in Python and other languages" --- ## External Kismet helpers Kismet implements a protobuf-based IPC system for communicating with external tools. This system is used to manage datasources and capture data, but it can also be used to extend the Kismet functionality without writing C++ code loaded directly into Kismet. ### What helper plugins can do Helper plugins are meant to provide additional functionality exposed via the Kismet web endpoints. Generally they are useful for managing long-running external processes which operate on Kismet data; for example, running analysis on a pcap log or providing mapping from the Kismet UI to another tool. Helper plugins can provide GET and POST endpoints, streaming data over an endpoint, and can also provide Javascript modules and HTTP to integrate with the web UI. Helper plugins can automatically request a HTTP authentication key for accessing the Kismet REST endpoints. ### What helper plugins cannot do Helper plugins do NOT run as part of Kismet - they are a separate process and communicate over IPC. They can not directly implement internal parts of Kismet; they are limited to interacting with Kismet over the existing REST endpoints. ## Plugin manifest The plugin manifest tells Kismet how to load the plugin. Described more fully in [general plugin documentation](/docs/devel/plugins/), all plugins should define a name, author, description, and version: ``` name=externaldemo author=Foo Bar description=External API demo plugin version=2020-00-00 ``` To load an external API plugin, you also need the `kisexternal` option (new as of 2020-07): ``` name=externaldemo author=Foo Bar description=External API demo plugin version=2020-00-00 kisexternal=kismet_externaldemo ``` This tells Kismet to run `kismet_externaldemo` as an IPC command. External API plugins can be combined with Javascript modules, as well; you can [make a Javascript module](/docs/devel/webui_basics/) and reference it in your manifest. This lets you make a custom UI that interacts with your endpoints. ``` name=externaldemo author=Foo Bar description=External API demo plugin version=2020-00-00 kisexternal=kismet_externaldemo js=demo_web_module,/plugin/externaldemo/js/demo_web_module.js ``` ## Helper executable The external helper tool is run by Kismet and communicates over the [helper RPC interface](/docs/devel/exteral_helper_tools/). The helper tool can be in any language which can talk the IPC protocol over a pipe(2) channel; for our examples we'll use Python and the KismetExternal module. ### Installing KismetExternal KismetExternal has its own repository. It will be migrated to a proper external module, installable via `pip`, but for now this guide will assume you're installing it via `setup.py`: ```bash $ git clone https://www.kismetwireless.net/git/python-kismet-external.git $ cd python-kismet-external $ python3 ./setup.py build $ sudo python3 ./setup.py install ``` ### Importing the basics We need to import a few basic elements into our helper. We also try to present a more meaningful message to the user if KismetExternal isn't available. ```python #!/usr/bin/env python3 import argparse import os import sys import threading import time try: import KismetExternal except ImportError: print("ERROR: We require the KismetExternal module") sys.exit(1) ``` ### Parsing the arguments Kismet will pass us two arguments when we get launched; `--in-fd` and `--out-fd`; these are the endpoints of the pipe(2) IPC channel. We use the `argparse` module here, but you can use whatever you like to read the arguments. ```python class ExternalDemo(object): def __init__(self): self.parser = argparse.ArgumentParser(description='Kismet external helper demo') self.parser.add_argument('--in-fd', action="store", type=int, dest="infd") self.parser.add_argument('--out-fd', action="store", type=int, dest="outfd") self.results = self.parser.parse_args() if self.results.infd is None or self.results.outfd is None: print("ERROR: Kismet external helper tools are launched by Kismet itself; do not run them directly.") sys.exit(1) ``` ### Initializing the external interface KismetExternal provides a full threaded interface for handling the RPC communications. Once we initialize it, we can ask it for tokens and register callbacks. ```python self.kei = KismetExternal.ExternalInterface(self.results.infd, seld.results.outfd) ``` ### Getting an authentication token Talking to the Kismet REST endpoints requires an authentication token; rather than expose the username and password, or require each external tool to be configured with a login, the external tool can request a HTTP authentication token. This can be used as the `KISMET` session cookie in all HTTP requests to the Kismet server. Because RPC is asynchronous, we need to provide a callback. ```python self.kei.request_http_auth(self.handle_web_auth_token) ``` and then the callback: ```python def handle_web_auth_token(self): self.auth_token = self.kei.auth_token ``` A more complete callback might set a variable that initialization is complete, or start a thread that communicates with the Kismet server. ### Providing a REST endpoint Now for the most powerful part of the external API: providing our own REST endpoint for communicating with the world. Rest endpoints can process `GET` and `POST` methods, and like the auth method, call a callback function we provide. ```python self.kei.add_uri_handler("GET", "/externaldemo/python.html", self.handle_web_python) ``` Then for the callback itself, we return some basic HTML: ```python def handle_web_python(self, externalhandler, request): # Print some debug that will show up in the console Kismet is running in print("PYTHON - handle web req {} {} {}".format(request.req_id, request.method, request.uri)) # Return some HTML externalhandler.send_http_response(request.req_id, bytes("This is from python!", "UTF-8")) ``` Notice the conversion to bytes! Since a HTTP response could be anything (images, packets, etc) it's a raw byte object. In Python3, we need to encode our string appropriately, so be sure to do so! ### Providing a POST endpoint To receive data on our endpoint, we support a POST method; this is done with the same callback methods, but we use the `variable_Data` field from the requests: ```python self.kei.add_uri_handler("POST", "/externaldemo/post", self.handle_web_post) ``` and the callback: ```python def self.handle_web_post(self, externalhandler, request): # Iterate the variables for i in request.variable_data: print("PYTHON - POST {}:{}".format(i.field, i.content)) externalhandler.set_http_response(request.req_id, bytes("Python got a POST", "UTF-8")) ``` Notice again the conversion to bytes! ### Sending status to the Kismet server We can send arbitrary messages to the Kismet server via `send_message`: ```python self.kei.send_message("Status update from python!") ``` ### The rest There's a little more we need to do; we need to start the KismetExternal interface, and instantiate our object. We also need to define a service loop that runs for as long as the KismetExternal interface remains up. Our extremely basic, but complete, example would look like: ```python #!/usr/bin/env python3 import argparse import os import time import sys import threading # Pretty-print the failure try: import kismetexternal except ImportError: print("ERROR: Kismet external Python tools require the kismetexternal python ") print(" library; you can find it in the kismetexternal git or via pip") sys.exit(1) class KismetProxyTest(object): def __init__(self): # Try to parse the arguments to find the descriptors we need to give to # the kismet external tool; Kismet calls external helpers with a pre-made # set of pipes on --in-fd and --out-fd self.parser = argparse.ArgumentParser(description='Kismet External Python Example') self.parser.add_argument('--in-fd', action="store", type=int, dest="infd") self.parser.add_argument('--out-fd', action="store", type=int, dest="outfd") self.results = self.parser.parse_args() if self.results.infd is None or self.results.outfd is None: print("ERROR: Kismet external python tools are (typically) launched by ") print(" Kismet itself; running it on its own won't do what you want") sys.exit(1) # Initialize our external interface self.kei = kismetexternal.ExternalInterface(self.results.infd, self.results.outfd) # self.kei.debug = True # Start the external handler BEFORE we register our handlers, since we need to be # connected to send them! self.kei.start() # External tools can request a HTTP authentication token; this can be used as the # 'KISMET' session cookie to perform administrative actions against the Kismet # server self.kei.request_http_auth(self.handle_web_auth_token) # Add a URI handler; it doesn't need a login, and it returns HTML self.kei.add_uri_handler("GET", "/proxytest/python.html", self.handle_web_python) # Add a GET var test self.kei.add_uri_handler("GET", "/proxytest/python_get.html", self.handle_web_python_get) # Add a POST var test self.kei.add_uri_handler("POST", "/proxytest/python_post.html", self.handle_web_python_post) # Add a streaming handler self.kei.add_uri_handler("GET", "/proxytest/stream.raw", self.handle_web_stream) self.kei.send_message("Hello from python! This is sent over the IPC message bus.") # Start the IO loops running self.kei.run() # Callback for when we've gotten back our auth token for the webserver def handle_web_auth_token(self): print("ProxyTest got HTTP auth token", self.kei.auth_token) # Callback function for handling a req of our python.html endpoint def handle_web_python(self, externalhandler, request): print("PYTHON - Handle web req {} {} {}".format(request.req_id, request.method, request.uri)) # Print a static response externalhandler.send_http_response(request.req_id, bytes("This is from python!", "UTF-8")) # Callback function for handling a req of our variabls.html endpoint def handle_web_python_get(self, externalhandler, request): print("PYTHON - Handle web req {} {} {}".format(request.req_id, request.method, request.uri)) print("PYTHON - GET variables ") for i in request.variable_data: print("PYTHON - GET {}:{}".format(i.field, i.content)) externalhandler.send_http_response(request.req_id, bytes("This is from python!", "UTF-8")) # Callback function for handling a req of our variable.html endpoint def handle_web_python_post(self, externalhandler, request): print("PYTHON - Handle web req {} {} {}".format(request.req_id, request.method, request.uri)) for i in request.variable_data: print("PYTHON - POST {}:{}".format(i.field, i.content)) externalhandler.send_http_response(request.req_id, bytes("This is from python!", "UTF-8")) # Callback function to demonstrate streaming def handle_web_stream(self, externalhandler, request): externalhandler.send_http_response(request.req_id, bytes("Stream starting\n", "UTF-8"), stream = True, finished = False) # Make a thread that streams data out this request webthread = threading.Thread(target=self.stream_web_data, args=(externalhandler, request)) webthread.start() # Thread that streams a counter def stream_web_data(self, externalhandler, request): counter = 0 while self.kei.is_running: externalhandler.send_http_response(request.req_id, bytes("Stream {}\n".format(counter), "UTF-8"), stream = True, finished = False) counter += 1 time.sleep(0.5) # Loop forever def loop(self): while self.kei.is_running(): self.kei.send_ping() time.sleep(1) self.kei.kill() if __name__ == "__main__": # Make a proxytest and loop forever pt = KismetProxyTest() # Loop in a detached process pt.loop() ``` ## More examples You can find a similar implementation of this in the `plugin-httpproxytest/` directory in the Kismet git; this is a Python KismetExternal plugin which implements GET, POST, and streaming interfaces. kismet-docs-master/devel/rest/000077500000000000000000000000001372362651600166605ustar00rootroot00000000000000kismet-docs-master/devel/rest/000-rest_endpoints.md000066400000000000000000000017231372362651600225420ustar00rootroot00000000000000--- title: "REST webserver endpoints" permalink: /docs/devel/webui_rest/endpoints/ docgroup: "devel-rest" excerpt: "The Kismet REST-like API" --- Kismet uses a REST-like interface for the embedded webserver, which provides data and accepts commands. When fetching data, whenever possible, parameters are passed as part of the GET URI, but for more complex features, command arguments may be sent via POST variables. Kismet supports multiple output formats; whenever possible, an endpoint will support all output formats. The default output format used in examples is JSON, but additional output types may be added in the future or added by run-time plugins. Some unique endpoints are available only under specific output methods because they take advantage of features of that output type. As of `2019-04-git`, Kismet requires a login on ALL rest endpoints, excluding `/system/user_status`, `/session/check_login`, `/session/check_session`, and `/session/check_setup_ok` kismet-docs-master/devel/rest/001-api_updates.md000066400000000000000000000052311372362651600217770ustar00rootroot00000000000000--- title: "API Changes and Updates" permalink: /docs/devel/webui_rest/changes/ docgroup: "devel-rest" excerpt: "Significant changes to the API endpoints" --- Over time, the Kismet endpoint API will change - while efforts are made to retain compatibility whenever possible, some changes will require breaking older implementations. These significant changes will be documented here. * `2020-08` several maps made optional/dynamic To save RAM, several maps and vectors are now flagged as optional; if there is no content in those fields, they will not be present in the generated JSON. Consumers should always check for presence of the map in the returned data before trying to use it. Fields made dynamic: * `kismet.device.base.tags` * `dot11.device/dot11.device.client_map` * `dot11.device/dot11.device.advertised_ssid_map` * `dot11.device/dot11.device.probed_ssid_map` * `dot11.device/dot11.device.associated_client_map` * `dot11.device/dot11.device.wpa_nonce_list` * `dot11.device/dot11.device.wpa_anonce_list` To save RAM, the `kismet.device.base.tags` sub-map is now optional; if there are no tags in a device, this field will not exist in the serialized JSON data. Consumers of this data should check that `kismet.device.base.tags` is present in the device map. * `2019-10` geopoint To more cleanly support ELK, all location records now use `geopoint` formats. A geopoint is an array containing `[lon, lat]`. `kismet.common.location.lat` and `kismet.common.location.lon` are now `kismet.common.location.geopoint`. * `2019-10` advertised_ssid and probe_ssid as arrays To more cleanly support ELK the advertised ssid and probed ssid components of dot11 devices are now serialized as vectors instead of maps. Previously these were serialized as maps with a key of the hash of the SSID and attributes (an essentialy meaningless number in the export). Now these are sent as an array of advertised or probed SSID objects. * `2019-10` ekjson and itjson To more cleanly support ELK EKJSON format, the `ekjson` serialization now permutes the field names to transform all `.` to `_`. This brings it in line with the ELK interpretation that a `.` is a field separator. To access the old implemention, where the field names are unmodified, use the new `itjson` (or 'iterative json') format; it will return results which are a vector of objects as an object per line, suitable for serialized parsing and processing. * `2019-04` Mandatory authentication Kismet now requires authentication on *ALL* endpoints, with the exclusion of `/system/user_status`, `/session/check_login`, `/session/check_session`, and `/session/check_setup_ok`. kismet-docs-master/devel/rest/005-exploring.md000066400000000000000000000112731372362651600215170ustar00rootroot00000000000000--- title: "Exploring endpoints" permalink: /docs/devel/webui_rest/exploring/ docgroup: "devel-rest" excerpt: "Exploring the REST API should be simple, here's how to get the most out of the endpoints and self-documenting fields." --- ## Exploring the REST system The easiest way to explore the REST system, aside from the docs, is to query the JSON endpoints directly. Remember that as of `2019-04-git` you will need to have a valid login to explore the server setup. You can use `curl` and `python` to quickly grab output and format the JSON to be human readable: ``` $ curl http://user:password@localhost:2501/datasource/all_sources.json | python -mjson.tool % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 36274 100 36274 0 0 761k 0 --:--:-- --:--:-- --:--:-- 770k [ { "kismet.datasource.capture_interface": "wlp3s0mon", "kismet.datasource.channel": "", "kismet.datasource.channels": [ "1", "1HT40+", "2", "3", "4", "5", "6", "6HT40-", "6HT40+", "7", "8", "9", "10", "11", "11HT40-" ], "kismet.datasource.definition": "wlp3s0", "kismet.datasource.dlt": 127, "kismet.datasource.error": 0, "kismet.datasource.error_reason": "", "kismet.datasource.hop_channels": [ .... ``` Similarly, POST data can be sent via curl; for example to test creating an alert via the dynamic alerts endpoint: ```bash $ curl -d 'json={"name": "JSONALERT", "description": "Dynamic alert added at runtime", "throttle": "10/min", "burst": "1/sec"}' http://username:password@localhost:2501/alerts/definitions/define_alert.cmd ``` which passes the parameters in the `json=` variable, and the login and password in the URI (username:password in this example). ### Basic Auth and Wget Kismet will return a `HTTP 401` error for unauthorized access, and accepts logins data via HTTP Basic Auth or the auth session cookie. Because Kismet interacts with the browser, it cannot set the standard `Www-Authenticate` header in the 401 response, as this would break the webui interaction; however, some tools, like Wget, will not select HTTP basic auth. Other tools, like Curl, python3-requests, etc, allow setting HTTP basic auth directly. Examples here will use `curl` for this reason. ### What do all the fields mean? More information about each field can be found in the `/system/tracked_fields.html` URI by visiting `http://username:password@localhost:2501/system/tracked_fields.html` in your browser. This will show the field names, descriptions, and data types, for every known entity. ### Additional pretty-printed output For even more information, almost every REST endpoint can be requested using the `{foo}.prettyjson` format; this JSON output is styled for ease of readability and includes additional metadata to help understand the format; for example: ``` $ curl http://username:password@localhost:2501/system/status.prettyjson { "description.kismet.device.packets_rrd": "string, RRD of total packets seen", "kismet.device.packets_rrd": { "description.kismet.common.rrd.last_time": "uint64_t, last time udpated", "kismet.common.rrd.last_time": 1506473162, ... "description.kismet.system.battery.percentage": "int32_t, remaining battery percentage", "kismet.system.battery.percentage": 96, "description.kismet.system.battery.charging": "string, battery charging state", "kismet.system.battery.charging": "discharging", "description.kismet.system.battery.ac": "uint8_t, on AC power", "kismet.system.battery.ac": 0, "description.kismet.system.battery.remaining": "uint32_t, battery remaining in seconds", "kismet.system.battery.remaining": 0, "description.kismet.system.timestamp.sec": "uint64_t, system timestamp, seconds", "kismet.system.timestamp.sec": 1506473162, } } ``` For each defined field, Kismet will include a metadata field, `description.whatever.field.name`, which gives the type (for instance, uint32_t for a 32bit unsigned int), and the description, for instance 'battery remaining in seconds'. While the `prettyjson` format is well suited for learning about Kismet and developing tools to interface with the REST API, the `json` format should be used for final code; it is significantly faster than `prettyjson` and is optimized for processing time and space. `prettyjson` should work with nearly all REST endpoints which return JSON records, but will *NOT* work with `ekjson`-only endpoints (which are relatively rare, and documented accordingly below in the REST docs). kismet-docs-master/devel/rest/010-serialization.md000066400000000000000000000040601372362651600223550ustar00rootroot00000000000000--- title: "Serialization types" permalink: /docs/devel/webui_rest/serialization/ docgroup: "devel-rest" excerpt: "Data can be serialized in several different ways, as traditional JSON, streaming pseudo-JSON for large queries, and as 'pretty' output for learning the API." --- ## Serialization Types Kismet can export data as several different formats; generally these formats are indicated by the type of endpoint being requested (such as foo.json) ### JSON Kismet will export objects in traditional JSON format suitable for consumption in javascript or any other language with a JSON interpreter. ### EKJSON "EK" JSON is modeled after the Elastic Search JSON format, where a complete JSON object is found on each line of the output. Kismet supports ekjson on any REST endpoint which returns a vector/list/array of results. *Added 2019-10* To be compatible with the ELK interpretation of field names, Kismet now permutes all field names in `ekjson` output, replacing all instances of `.` with `_`. ### ITJSON *Added 2019-10* "IT" or "Iterative" JSON is a variant of JSON optimized for large vector/array data sets. Instead of containing the entire output in a JSON array, each element of the array is sent on its own newline. *All non-ELK use of previous ekjson endpoints should now use itjson endpoints*. The ekjson serialization now modifies field names. Kismet supports itjson on any REST endpoint which returns a vector/list/array of results. The itjson results must be parsed *as a stream* instead of *as a traditional JSON object*. Attempting to parse an itjson response as traditional JSON will result in syntax errors. ### PRETTYJSON "Pretty" JSON is optimized for human readability and includes metadata fields describing what Kismet knows about each field in the JSON response. For more information, see the previous section, `Exploring the REST system`. "Pretty" JSON should only be used for learning about Kismet and developing; for actual use of the REST API standard "JSON" or "EKJSON" endpoints should be used as they are significantly faster and optimized. kismet-docs-master/devel/rest/015-logins_and_sessions.md000066400000000000000000000075141372362651600235570ustar00rootroot00000000000000--- title: "Logins and sessions" permalink: /docs/devel/webui_rest/logins/ docgroup: "devel-rest" excerpt: "Kismet uses a standard login and session cookie system which is easily supported by most HTTP libraries." --- Kismet uses HTTP basic-auth to submit login information, and session cookies to retain login state. As of `2019-04-git`, all interaction with the Kismet server requires a login. A session will automatically be created during authentication to any endpoint which requires login information, and returned in the `KISMET` session cookie. Logins may be manually validated against the `/session/check_session` endpoint if validating user-supplied credentials. ### First login The first time Kismet is started, the user must set a password. Until the password is set, endpoints which require a login will be disabled and will return an error. External tools (and UI implementations) can check if the initial password has been set. Typically this API should not be used unless you are implementing a new Kismet UI that needs to provision the first-use scenario. If you wish to pre-configure a Kismet server username and login, refer to [the webserver configuration documentation](/docs/readme/webserver). * URL \\ /session/check_setup_ok * API added \\ `2019-01` * Methods \\ `GET` * Result \\ `HTTP 200` is returned if the initial setup has been completed. \\ `HTTP 406` NOT ACCEPTABLE is returned if the credentials are hard-coded into the global configuration. \\ HTTP error is returned if the initial setup has not been completed and the user is required to set a password. * Notes \\ If the password is set in the global Kismet configuration files, such as `kismet_httpd.conf` or `kismet_site.conf`, this API will not be available and will return an error. ### Setting the login The initial login must be set before the user can access any restricted endpoints. This endpoint can also be used to set a new login. * URL \\ /session/set_password * API added \\ `2019-01` * Methods \\ `POST` * POST parameters \\ Standard `HTTP POST` variables, including: | Key | Description | | --- | ----------- | | username | Optional, username for new login. If not provided, will default to `kismet`. | | password | Required, new password. | * Results \\ `HTTP 200` is returned if the password set was successful. \\ `HTTP 406` NOT ACCEPTABLE is returned if the server password is set in the global configuration. \\ HTTP error is returned if the password set was unsuccessful. * Notes \\ Setting the initial password does not require a login. Subsequent attempts to change the login and password *will* require a valid login session for the current password value, and will not invalidate any current login sessions. \\ If the password is set in the global Kismet configuration files, such as `kismet_httpd.conf` or `kismet_site.conf`, this API will not be available and will return an error. ### Checking sessions A script can check for a valid session and prompt the user to take action if a session is no longer valid. Login data may be provided; if the session is not valid, and valid login data is provided via basic auth, a session will be created. * URL \\ /session/check_session * Methods \\ `GET` * Result \\ `HTTP 200` is returned if the session is valid. \\ HTTP error returned if session is *not* valid and supplied login data, if any, is not valid. ### Checking logins A script may need to check for a valid login and prompt the user to take action if the login credentials are not valid. Session cookies will be ignored while checking logins. * URL \\ /session/check_login * Methods \\ `GET` * Result \\ `HTTP 200` is returned if the login is valid. \\ HTTP error returned if the login is not valid. kismet-docs-master/devel/rest/020-commands.md000066400000000000000000000133021372362651600213010ustar00rootroot00000000000000--- title: "Commands" permalink: /docs/devel/webui_rest/commands/ toc: true docgroup: "devel-rest" excerpt: "Commands (actionable API calls) use a common method for defining arguments and options." --- Commands are sent via HTTP POST. Command options are sent as a JSON dictionary object in the POST field `json` This may be subject to change as the HTTP interface evolves. Commands should always be sent using the `x-www-form-encoded` content type; if your API does not do this by default, you may need to specify: ```javascript Content-Type: application/x-www-form-urlencoded; charset=utf-8 ``` as part of the requests you send. Command dictionaries should be sent as a JSON dictionary in the `json` POST variable. ### Generating commands A simple Javascript generator might look similar to: ```javascript var json = { "cmd": "lock", "channel": "6", "uuid": "aaa:bbb:cc:dd:ee:ff:gg" }; var postdata = "json=" + JSON.stringify(json); $.post("/some/endpoint", data = postdata, dataType = "json"); ``` Similarly, commands can be sent from the command line: ```bash $ curl -d 'json={"cmd": "lock", "channel": 6}' http://host:port/some/endpoint ``` Commands are encoded as dictionaries to allow flexibility across calling platforms, as well as forward-compatibility as endpoints evolve. Adding additional keys to an options dictionary should not cause an older version of the server code to return an error. Dictionary key values are case sensitive. ### Timestamps Kismet allows both absolute and relative timestamps in almost all APIs which accept a timestamp value; those APIs which only work with an absolute timestamp will be denoted specially. An absolute timestamp value is a Unix timestamp in seconds since the timestamp epoch. All positive timestamp values are interpreted as absolute, epochal timestamps. A relative timestamp is calculated automatically by the Kismet server as relative from *now*. All negative timestamp values are interpreted as relative timestamps, and interpreted as (*now* - *timestamp*). Relative timestamps are useful for fetching events from the past *N* seconds, without needing to know the current timestamp of the server. ### Field Specifications Most endpoints which return records will also accept a field specification as part of the command dictionary. Field specifications allow the simplification of the data being returned, analogous to `select a, b, c` instead of `select *` in SQL. Simplifying fields, especially when performing very large queries, reduces the CPU and memory requiremets of Kismet *and* the client by reducing the amount of data being serialized, transmitted, and deserialized. Users of the REST API are *strongly* encouraged to make use of field simplification whenever plausible. Field specification objects take the format of a vector/array containing multiple field definitions: ```python [ field1, ... fieldN ] ``` where a field may be a single element string, defining a field name or a field path, such as: * `'kismet.device.base.channel'` * `'kismet.device.base.signal/kismet.common.signal.last_signal'` *or* a field may be a two-element array, consisting of a field name or path, and a target name the field will be aliased as, for example: * `['kismet.device.base.channel', 'base.channel']` * `['kismet.device.base.signal/kismet.common.signal.last_signal', 'base.last.signal']` Fields will be returned in the device as their final path name: that is, from the above example, the device would contain: `['kismet.device.base.channel', 'kismet.common.signal.last_signal']` And from the second example, it would contain: `['base.channel', 'base.last.signal']` When requesting multiple fields from different paths with the same name - for instance, multiple signal paths provide the `kismet.common.signal.last_signal` - it is important to provide an alias. Fields which resolve to the same name will only be present in the results once, and the order is undefined. ### Regex filters Some endpoints in Kismet take a regex object. These endpoints use a common format, which allows for multiple regular expressions to be mapped to multiple fields. A device is considered to match if *any* of the regular expression terms are true. If the Kismet server was compiled without libpcre support, passing a regular expression to an endpoint will cause the endpoint to return an error. ```python [ [ multifield, regex ], ... [ multifield, regex ] ] ``` #### `multifield` `multifield` is a standard field path, but it will be automatically expanded to match all values if a vector or value-map field is encountered in the path. For example, the multifield path: `'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid'` will be expanded to include all `dot11.advertisedssid` objects in the `advetised_ssid_map` dictionary, and will apply to the `dot11.advertisedssid.ssid` field in each. Similarly, vectors, intmaps, doublemaps, macmaps, and so forth will be expanded, allowing matching against nested fields. The field is expected to resolve as a string: if it is not a string, the regex will be considered to not match. #### `regex` `regex` is a simple string containing a PCRE-compatible regular expression. #### Example For example, to match on SSIDs, a regex object might be: ```python regex = [ [ 'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid', '^SomePrefix.*' ], [ 'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid', '^Linksys$' ] ] ``` For extracting over curl, a similar example: ```bash $ curl -d \ "{'regex': 'dot11.device/dot11.device.advertised_ssid_map/dot11.advertisedssid.ssid', '^Linksys$']}" \ http://user:password@server:2501/devices/views/phydot11_accesspoints/devices.json ``` kismet-docs-master/devel/rest/021-keys_and_macs.md000066400000000000000000000030051372362651600223000ustar00rootroot00000000000000--- title: "Keys and MAC addresses" permalink: /docs/devel/webui_rest/keys_and_macs/ toc: true docgroup: "devel-rest" excerpt: "The differences between keys and macs, and optional MAC group matching." --- ## MAC addresses The MAC address is a theoretically unique identifier given to a device at manufacture time. For Ethernet and Wi-Fi devices, this is assigned by the IEEE, and must be unique. Typically a MAC address is 6 bytes. Kismet supports MAC addresses up to 8 bytes, however no PHYs currently use these. Kismet will attempt to synthesize MAC addresses for PHYs which do not present traditional MAC addresses. ## Keys Kismet uses a unique key for each device. The key is *derived from* the MAC address, but contains additional information about the PHY type. This allows multiple devices to have the same MAC address under different PHY types without overlap; this can be of particular importance when using non-traditional PHY types which do not use strict device identifiers. ## MAC address masking On queries and filters affecting MAC addresses, Kismet supports complete addresses or partial addresses with masking. A masked address resembles the syntax typically used for IP network masking: `[MAC]/[MASK]`. For instance, to match only the OUI, a masked MAC of: ```json "aa:bb:cc:00:00:00/ff:ff:ff:00:00:00" ``` This would match any MAC address where the OUI, or first three bytes, are "aa:bb:cc". A similar feature to match on the first *four* bytes would be: ```json "aa:bb:cc:dd:00:00/ff:ff:ff:ff:00:00" ``` kismet-docs-master/devel/rest/030-system.md000066400000000000000000000021661372362651600210330ustar00rootroot00000000000000--- title: "System status" permalink: /docs/devel/webui_rest/system_status/ toc: true docgroup: "devel-rest" excerpt: "Basic system status and health reporting." --- ## System status * URL \\ /system/status.json * Methods \\ `GET` `POST` * POST parameters | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Result \\ Dictionary of Kismet system-level status, including update, battery, memory, and thermal data, optionally simplified. ## Timestamp * URL \\ /system/timestamp.json * Methods \\ `GET` * Result \\ Dictionary of system timestamp as second, microsecond; can be used to synchronize timestamps and as a keep-alive check. ## Tracked fields * URL \\ /system/tracked_fields.html * Methods \\ `GET` * Result \\ Human-readable table of all registered field names, types, and descriptions. While it cannot represent the nested features of some data structures, it will describe every allocated field. This endpoint returns a HTML document for ease of use. kismet-docs-master/devel/rest/035-devices.md000066400000000000000000000330061372362651600211330ustar00rootroot00000000000000--- title: "Devices" permalink: /docs/devel/webui_rest/devices/ toc: true docgroup: "devel-rest" excerpt: "Device listing, sorting, and related interfaces." --- A device is the central record of a tracked entity in Kismet. Clients, bridges, access points, wireless sensors, and any other type of entity seen by Kismet will be a device. For complex relationships (such as 802.11 Wi-Fi), a list of related devices describes the access point-client relationship. All devices will have a basic set of records (held in the `kismet.base.foo` group of fields, generally) and sub-trees of records attached by the phy-specific handlers. A device may have multiple phy-specific records, for instance a device may contain both a `device.dot11` record and a `device.uav` record if it is seen to be a Wi-Fi based UAV/Drone device. The preferred method of retrieving device lists is to use the POST URI `/devices/summary/` or `/devices/last-time` with a list of fields provided. Whenever possible, limiting the fields requested and the time range requested will reduce the load on the Kismet server *and* the client consuming the data. ## Device summary and windowed device view The device tracker uses [device views](/docs/devel/webui_rest/device_views/) to provide a windowed, sortable, searchable device list. This list is used by the main Kismet UI to display all devices, for instance. This API supercedes the `/devices/summary/` API. * URL \\ /devices/views/all/... /devices/views/all/devices.json /devices/views/all/last-time/*[TIMESTAMP]*/devices.json * API added \\ `2019-06` * Notes \\ See the [views api](/docs/devel/webui_rest/device_views/) for detailed information on how to use the views endpoints. ## Old Summarization & display The device summarization endpoint is the primary interface for clients to access the device list. It is used heavily by the Kismet UI for the main device list table. The device summarization is best utilized when applying a view window via the `start` and `length` variables. * URL \\ /devices/summary/devices.json * DEPRECATED \\ `2019-06` While still available, this API has been deprecated in favor of the `all` device view. * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------- | ----------------------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | | colmap | Optional column correlation info inserted by the Kismet Datatable UI for mapping jquery-datatables column information for proper ordering and sorting. | | datatable | Optional, inserted by the Kismet Datatable UI to enable datatable mode which wraps the output in a container suitable for consumption by jquery-datatables. | Additionally, when in datatables mode, the following HTTP POST variables are used: | Key | Description | | --- | ---- | | start | Data view window start position | | length | Datatable window end | | draw | Datatable draw value | | search[value] | Search term, applied to all fields in the summary vector | | order\[0\]\[column\] | Display column number for sorting, indexed with colmap data | | order\[0\]\[dir\] | Sort order direction from jquery-datatables | * Results \\ Summarized vector of devices. ## Bulk device list A special `ekjson`-only endpoint which provides a dump of all devices. This endpoint *only* returns ekjson-formatted data. This endpoint is most useful for extracting bulk data and passing it to another tool like Elasticsearch. * URL \\ /devices/all_devices.ekjson * Methods \\ `GET` `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------ | ---------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Each device is returned as a JSON object, one JSON record per line. ## Activity & timestamp Fetch devices which have been active since the supplied timestamp. This endpoint is typically used by scripted clients to monitor currently active devices. * URL \\ /devices/last-time/*[TIMESTAMP]*/devices.json \\ /devices/last-time/*[TIMESTAMP]*/devices.ekjson * Methods \\ `GET` `POST` * URL parameters \\ | Key | Description | | ------ | ---------------------------------------- | | *[TIMESTAMP]* | Relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------ | ---------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | * Results \\ Vector of (optionally summarized and filtered) devices active since *TS* ## Device by key Fetch devices by the Kismet device key. * URL \\ /devices/by-key/*[DEVICEKEY]*/device.json * Methods \\ `GET` `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[DEVICEKEY]* | Kismet unique device key to match | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------ | ----------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Device record, with optional simplification of the fields, matching *DEVICEKEY* ## Device by MAC Fetch devices which match the supplied MAC address. It is possible (though usually not likely) that there may be MAC address collisions between different PHY types. This becomes more likely when using non-Wi-Fi capture types which synthesize false MAC addresses because no official address is available, such as RTL-433, Mousejack, and other SDR-based datasources. This API will always return a vector of devices, even when only one device matches the MAC address. * URL \\ /devices/by-mac/*[MACADDRESS]*/devices.json * Methods \\ `GET` `POST` * URL Parameters | Key | Description | | ------ | ----------- | | *[MACADDRESS]* | Device MAC address to match | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------ | ----------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Array of all devices with the supplied MAC address, optionally simplified by `fields` parameter. ## Multiple devices by MAC Fetch devices matching any of multiple MAC addresses (or partial MAC addresses). Typically used to monitor the presence of target devices. This API will always return a vector of devices, even when only one device is matched. The supplied MAC addresses can either be complete MACs (`aa:bb:cc:dd:ee:ff`), or partial-match masked MACs; for instance to match only the OUI `00:aa:bb`, a masked MAC address of `00:aa:bb:00:00:00/ff:ff:ff:00:00:00` can be supplied, as defined in [Keys and MAC addresses](/docs/devel/webui_rest/keys_and_macs/). * URL \\ /devices/multimac/devices.json * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Desc | | ------ | ----------------------------------- | | devices | Required, a vector of MAC addresses to be returned | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Array of all devices matching any of the supplied MAC addresses. ## Multiple devices by key Fetch multiple devices matching any of the supplied keys. Typically used to retrieve the bulk status of many devices for display in the UI. This API will always return a vector of devices, even when only one device is matched. If a supplied key is not found, no device will be returned for that key. * URL \\ /devices/multikey/devices.json * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Desc | | ------ | ----------------------------------- | | devices | Required, a vector of device keys to be returned | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Array of all devices matching any of the supplied device keys. ## Multiple devices by key (dictionary) Fetch multiple devices matching any of the supplied keys. Typically used to retrieve the bulk status of many devices for display in the UI. This API will always return a vector of devices, even when only one device is matched. If a supplied key is not found, no device will be returned for that key. * URL /devices/multikey/as-object/devices.json * API added `2020-08` * Methods `POST` * POST parameters A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Desc | | ------ | ----------------------------------- | | devices | Required, a vector of device keys to be returned | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results Dictionary of all devices matching any of the supplied device keys, indexed by key. ## Devices by capture source The device tracker uses [device views](/docs/devel/webui_rest/device_views/) to provide a list of devices filtered by capturing data source: * URL \\ /devices/views/seenby-uuid/[*UUID*]/... /devices/views/seenby-uuid/[*UUID*]/devices.json /devices/views/seenby-uuid/[*UUID*]/last-time/*[TIMESTAMP]*/devices.json * API added \\ `2019-03` * URL Parameters | Key | Description | | ------ | ----------- | | *[UUID]* | UUID of datasource | * Notes \\ See the [views api](/docs/devel/webui_rest/device_views/) for detailed information on how to use the views endpoints. ## Phy handlers A PHY handler in Kismet processes packets of a given physical layer; for instance Wi-Fi, Bluetooth, etc. * URL \\ /phy/all_phys.json * Methods \\ `GET` `POST` * API added \\ `2019-03` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------ | ----------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Array of all phy types, including phy name, internal reference number, and packet and device counts. ## Devices by PHY type The device tracker uses [device views](/docs/devel/webui_rest/device_views/) to provide a list of devices filtered by the PHY data type: * URL \\ /devices/views/phy/[*PHYNAME*]/... /devices/views/phy/[*PHYNAME*]/devices.json /devices/views/phy/[*PHYNAME*]/last-time/*[TIMESTAMP]*/devices.json * API added \\ `2019-03` * URL Parameters | Key | Description | | ------ | ----------- | | *[PHYNAME]* | UUID of datasource | * Notes \\ See the [views api](/docs/devel/webui_rest/device_views/) for detailed information on how to use the views endpoints. ## Editing - device names Devices can have an arbitrary user-supplied name. * URL \\ /devices/by-key/*[DEVICEKEY]*/set_name.cmd * Methods \\ `POST` * URL Parameters | Key | Description | | ------ | ----------- | | *[DEVICEKEY]* | Key of device to edit | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | username | New name for device | * Results \\ `HTTP 200` on success \\ HTTP error on failure ## Editing - device tags Devices contain a collection of arbitrary tags which are held in the `kismet.device.base.tags` tree of the device record. These tags can be used to store persistent notes or other user-supplied or auto-generated data, and are keyed by the string tag name. * URL \\ /devices/by-key/*[DEVICEKEY]*/set_tag.cmd * Methods \\ `POST` * URL Parameters | Key | Description | | ------ | ----------- | | *[DEVICEKEY]* | Key of device to edit | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | tagname | Tag being altered | | tagvalue | Tag value being set | * Results \\ `HTTP 200` on success \\ HTTP error on failure kismet-docs-master/devel/rest/040-device_views.md000066400000000000000000000071401372362651600221610ustar00rootroot00000000000000--- title: "Device views" permalink: /docs/devel/webui_rest/device_views/ toc: true docgroup: "devel-rest" excerpt: "A common 'device view' API which is used by many components of Kismet to present different views of the device data while retaining identical API calls." --- ## Device views Device views are optimized subsets of the global device list. Device views can be defined by PHY handlers, plugins, as part of the base Kismet code, or user-supplied data. All device views respond to the same common API; any code which access a specific device view should be portable across multiple views. ### View list The view list shows all defined device views and a summary of the number of devices in each. * URL \\ /devices/views/all_views.json * Methods \\ `GET` * Results \\ Array of device views and device counts per view. ### View-based summarization and display Mirroring the [base summarization & display endpoint](/docs/devel/webui_rest/devices/#old-summarization--display) API, the view summarization endpoint is the primary interface for clients to access the device list and for scripts to retrieve lists of devices. The device summarization is best utilized when applying a view window via the `start` and `length` variables. * URL \\ /devices/views/*[VIEWID]*/devices.json * Methods \\ `POST` * URL parameters | Key | Description | | --- | ----------- | | *[VIEWID]* | Kismet view ID | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------- | ----------------------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | | colmap | Optional, inserted by the Kismet Datatable UI for mapping column information for proper ordering and sorting. | | datatable | Optional, inserted by the Kismet Datatable UI to enable datatable mode which wraps the output in a container suitable for consumption by jquery-datatables. | Additionally, when in datatables mode, the following HTTP POST variables are used: | Key | Description | | --- | ---- | | start | Data view window start position | | length | Datatable window end | | draw | Datatable draw value | | search[value] | Search term, applied to all fields in the summary vector | | order\[0\]\[column\] | Display column number for sorting, indexed with colmap data | | order\[0\]\[dir\] | Sort order direction from jquery-datatables | * Results \\ Summarized array of devices. ### Devices by view & time Mirroring the [Activity & timestamp](/docs/devel/webui_rest/devices/#activity--timestamp) API, fetches devices from a specified view which have been active since the supplied timestamp. This endpoint is typically used by scripted clients to monitor active devices within a view. * URL \\ /devices/views/*[VIEWID]*/last-time/*[TIMESTAMP]*/devices.json * Methods \\ `GET` `POST` * URL parameters | Key | Description | | --- | ----------- | | *[VIEWID]* | Kismet view ID | | *[TIMESTAMP]* | Relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ Array of devices in view *VIEWID* with activity more recent than *TIMESTAMP* with optional field simplification. kismet-docs-master/devel/rest/045-messages.md000066400000000000000000000016271372362651600213250ustar00rootroot00000000000000--- title: "Messages" permalink: /docs/devel/webui_rest/messages/ toc: true docgroup: "devel-rest" excerpt: "Kismet exposes the console messages via the messagebus API." --- Kismet uses an internal `messagebus` system for communicating text messages from system components to the user. The messagebus is used to pass error, state, and debug messages, as well as notifications to the user about detected devices, alerts, etc. ## All messages * URL \\ /messagebus/all_messages.json * Method \\ `GET` * Result \\ Array of the last 50 messages in the messagebus ## Recent messages * URL \\ /messagebus/last-time/*[TIMESTAMP]*/messages.json * Method \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[TIMESTAMP]* | Relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | * Result \\ Array of messages since *TIMESTAMP* kismet-docs-master/devel/rest/050-alerts.md000066400000000000000000000112311372362651600207740ustar00rootroot00000000000000--- title: "Alerts" permalink: /docs/devel/webui_rest/alerts/ toc: true docgroup: "devel-rest" excerpt: "The alerts API allows for fetching raised alerts, defining new custom alerts purely via the API interface, and raising alerts via the API interface, allowing external tools to tie into the Kismet alert subsystem." --- Kismet alerts notify the user of critical Kismet events and wireless intrusion events. Alerts are generated as messages (sent via [the messagebus](/docs/devel/webui_rest/messages/)) and as alert records. ## Alert configuration Kismet exposes the full alert system configuration, including currently supported alert types, full descriptions of alert content, and time and burst-rate delivery limiting. * URL \\ /alerts/definitions.json * Methods \\ `GET` * Result \\ Array of all alert records. ## All alerts Kismet retains the past *N* alerts, as defined in `kismet_alert.conf`. By default, Kismet retains 50 alert records. * URL \\ /alerts/all_alerts.json * Methods \\ `GET` * Result \\ Array of all currently stored alerts ## Recent alerts Alerts can be fetched by timestamp, returning only new alerts. This API takes a specialized timestamp value which includes microsecond precision. * URL \\ /alerts/last-time/*[TIMESTAMP.UTIMESTAMP]*/alerts.json * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[TIMESTAMP.UTIMESTAMP]* | A double-precision timestamp of the Unix epochal second timestamp *and* a microsecond precision sub-second timestamp. | * Result \\ An array containing an array of alerts since *TIMESTAMP.UTIMESTAMP*. ## Recent alerts (wrapped) Alerts can be fetched by timestamp, returning only new alerts. This API takes a specialized timestamp value which includes microsecond precision. This endpoint returns the exact timestamp, with microsecond precision, of the returned alerts; this allows a client UI to accurately display only the new alerts. * URL \\ /alerts/last-time/*[TIMESTAMP.UTIMESTAMP]*/alerts.json * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[TIMESTAMP.UTIMESTAMP]* | A double-precision timestamp of the Unix epochal second timestamp *and* a microsecond precision sub-second timestamp. | * Result \\ A *dictionary* containing an array of alerts since *TIMESTAMP.UTIMESTAMP* and a double-precision timestamp second and microsecond timestamp of the current server time. ## Defining alerts New alerts can be defined runtime, and triggered by external tools via the REST API. * URL \\ /alerts/definitions/define_alert.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ----------- | ---------------------------------------- | | name | Simple alert name/identifier | | description | Alert explanation / definition displayed to the user | | phyname | (Optional) name of phy this alert is associated with. If not provided, alert will apply to all phy types. If provided, the defined phy *must* be found or the alert will not be defined. | | throttle | Maximum number of alerts per time period, as defined in kismet.conf. Time period may be 'sec', 'min', 'hour', or 'day', for example '10/min' | | burst | Maximum number of sequential alerts per time period, as defined in kismet.conf. Time period may be 'sec', 'min', 'hour', or 'day'. Alerts will be throttled to this burst rate even when the overall limit has not been hit. For example, '1/sec' | * Results \\ `HTTP 200` on success \\ HTTP error on failure ## Raising alerts Alerts can be triggered by external tools; the alert must be defined, first. * URL \\ /alerts/raise_alerts.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------- | ---------------------------------------- | | name | Alert name/identifier. Must be a defined alert name. | | text | Human-readable text for alert | | bssid | (optional) MAC address of the BSSID, if Wi-Fi, related to this alert | | source | (optional) MAC address the source device which triggered this alert | | dest | (optional) MAC address of the destination device which triggered this alert | | other | (optional) Related other MAC address of the event which triggered this alert | | channel | (optional) Phy-specific channel definition of the event which triggered this alert | * Result \\ `HTTP 200` on success \\ HTTP error on failure kismet-docs-master/devel/rest/055-channels.md000066400000000000000000000005221372362651600213030ustar00rootroot00000000000000--- title: "Channels" permalink: /docs/devel/webui_rest/channels/ toc: true docgroup: "devel-rest" excerpt: "Observed channels and channel traffic API." --- ## System status * URL \\ /channels/channels.json * Methods \\ `GET` * Result \\ Dictionary containing channel usage, device counts, and coverage data. kismet-docs-master/devel/rest/060-datasources.md000066400000000000000000000204411372362651600220230ustar00rootroot00000000000000--- title: "Datasources" permalink: /docs/devel/webui_rest/datasources/ toc: true docgroup: "devel-rest" excerpt: "APIs for accessing defined, and potential, datasources, as well as controlling the behavior of datasources." --- Datasources in Kismet capture information - typically packets - and return them to the Kismet server for processing. Typically, a datasource is analogous to a network interface, but may encompass other capture options such as SDR. Datasources are defined on startup in `kismet.conf` via `source=...` or on the command line with `-c source definition...`. ## Supported datasource types Datasource types are defined by the Kismet server code and any plugins loaded. Clients can use this API to determine if Kismet has been started with the required plugins or compiled-in optional datasources. * URL \\ /datasource/types.json * Methods \\ `GET` * Result \\ Array of all defined datasource types ## Defaults Datasource defaults are defined in `kismet.conf` and include default hopping behavior, hopping speeds, and other generic options. If a datasource is defined without these options specified, the defaults are used. * URL \\ /datasource/defaults.json * Methods \\ `GET` * Result \\ Dictionary of default values ## Listing datasources Datasource listings include the definition of the source, current operational status, driver and backend information, packet counts, and historical data. * URL \\ /datasource/all_sources.json * Methods \\ `GET` * Result \\ Array of active data sources and all current information. ## Querying specific datasources * URL \\ /datasource/by-uuid/*[UUID]*/source.json * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * Results \\ Returns dictionary object of source specified by *UUID* ## Listing interfaces A *datasource* is a Kismet capture source which provides data. An *interface* is a potential device a datasource may capture from, such as `wlan0` or a RTLSDR USB device. This API is used by the Kismet web interface to add new datasources runtime. * URL \\ /datasource/list_interfaces.json * Methods \\ GET * Result \\ Array of auto-detected interfaces, currently attached datasources if any, and parameters. ## Adding sources Datasources may be dynamically added at runtime. New data sources require a full datasource definition, as if they were in a `source=` config line. * URL \\ /datasource/add_source.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | definition | Source definition line | * Result \\ `HTTP 200` is returned *when the source is successfully added*. A source *may be added which cannot be activated* if the definition is incorrect or the interface is not available. HTTP error is returned if the source could not be added. * Notes \\ This API will block until the source is added to Kismet. This may be up to several seconds but typically is instant. ## Setting channels Datasource channel configurations be configured to automatically hop over a list of channels, or remain fixed on a single channel. Channels are defined as strings and may contain complex information, such as `11HT40-` for a Wi-Fi channel 11 using 40MHz 802.11n. The exact format of a channel depends on the PHY type being configured. * URL \\ /datasource/by-uuid/*[UUID]*/set_channel.cmd * Methods \\ `POST` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Desc | | -------- | ---------------------------------------- | | channel | Single channel; This disables channel hopping and sets a specific channel. Channel format depends on the source. | | hoprate | Channel hopping speed, as channels per second. For timing greater than a second, rate can be calculated with the formula `hoprate = 1 / (6 / N)` where N is the number of hops per minute. | | channels | The list of channel strings to use in hopping | | shuffle | Integer 0 or 1, treated as boolean, tells the source to shuffle the channel list | * Results \\ `HTTP 200` is returned if the channel set command succeeded. Individual channels may not be tunable by the source. HTTP error is returned if the channel set command is not successful. * Notes \\ This API will block until the source channel configuration is complete. This may be up to several seconds but typically is instant. \\ The exact behavior of the source depends on the provided parameters: \\ If `channel` is present, `hoprate`, `channels`, and `shuffle` should not be included, and will be ignored if present. The source will be locked to a single channel. \\ If `channel` is not present, the remaining fields may be specified. \\ If `channels` is present, `hoprate` and `shuffle` are optional. If they are not present, the current values for the source will be used. \\ If `channel` is not present, `channels` is not present, and `hoprate` is set, only the channel hopping rate will be changed. \\ * Examples \\ `{'channel': "6HT40"}` will lock to Wi-Fi channel 6, HT40+ mode \\ `{'channels': ["1", "2", "6HT40+", "6HT40-"]}` will change the channel hopping list but retain the hopping rate and shuffle \\ `{'channels': ["1", "2", "3", "4", "5"], 'hoprate': 1}` will change the channel hopping rate to once per second over the given list \\ `{'hoprate': 5}` will set the hop rate to 5 channels per second, using the existing channels list in the datasource ## Set channel hopping Turn on channel hopping for the specified source, without altering the channel parameters. Typically used to enable hopping after inspecting a single channel. * URL \\ /datasource/by-uuid/*[UUID]*/set_hop.cmd * Methods \\ `POST` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * POST parameters: \\ None * Results \\ `HTTP 200` on success HTTP error if unable to set hopping ## Closing sources Sources can be closed and will no longer be processed. A source will remain closed unless reopened. * URL \\ /datasource/by-uuid/*[UUID]*/close_source.cmd \\ /datasource/by-uuid/*[UUID]/disable_source.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * Results \\ `HTTP 200` is returned if the source is successfully stopped \\ HTTP error is returned if the source could not be stopped ## Opening closed sources Closed sources can be re-opened. * URL \\ /datasource/by-uuid/*[UUID]*/open_source.cmd \\ /datasource/by-uuid/*[UUID]*/enable_source.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * Results \\ `HTTP 200` is returned if the open command succeeds. The source may still encounter errors. \\ HTTP error is returned if the source could not be opened. ## Pausing sources Paused sources are not closed, but packets received from them will be discard. This can be used to silence a source in some circumstances, but does not require shutting down the source and re-acquiring it later. * URL \\ /datasource/by-uuid/*[UUID]*/pause_source.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * Results \\ `HTTP 200` is returned if the pause command succeeds. \\ HTTP error is returned if the source could not be paused. ## Resuming sources A paused source can be resumed; upon resumption, new packets will be processed from this source. Packets received while the source was paused are lost. * URL \\ /datasource/by-uuid/*[UUID]*/resume_source.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[UUID]* | Source UUID | * Results \\ `HTTP 200` is returned if the resume command succeeds. \\ HTTP error is returned if the source could not be resumed. kismet-docs-master/devel/rest/065-gps.md000066400000000000000000000032131372362651600203020ustar00rootroot00000000000000--- title: "GPS" permalink: /docs/devel/webui_rest/gps/ toc: true docgroup: "devel-rest" excerpt: "Supported GPS devices, defined GPS devices, and current location information." --- Kismet now supports multiple simultaneous GPS devices, and can select the 'best' quality device based on priority and GPS signal. ## List all available GPS drivers Kismet supports multiple types of GPS device, and can be extended by plugins. * URL \\ /gps/drivers.json * Methods \\ `GET` * Return \\ Array of all supported GPS drivers ## List all GPS devices * URL \\ /gps/all_gps.json * Methods \\ `GET` * Return \\ All configured GPS devices ## GPS location The current "best" GPS location can be retrieved, with timestamp, for presentation in the UI or use in logging. * URL \\ /gps/location.json * Methods \\ `GET` * Return \\ Current GPS location and information ## Web GPS Kismet supports a Web-based GPS, where the data is provided by the browser (or submitted over the HTTP channel from another GPS source). * URL \\ /gps/web/update.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ---- | --------------------------------------- | | lat | GPS latitude | | lon | GPS longitude | | alt | Optional, GPS altitude in meters | | spd | Optional, GPS speed in kilometers per hour | * Returns \\ `HTTP 200` on successful update of the webgps location HTTP error on failure kismet-docs-master/devel/rest/070-packet_capture.md000066400000000000000000000045501372362651600225040ustar00rootroot00000000000000--- title: "Packet capture" permalink: /docs/devel/webui_rest/packet_capture/ toc: true docgroup: "devel-rest" excerpt: "Access the packet stream live with optional datasource and device filtering." --- Kismet can export packets in the pcap-ng format; this is a standard, extended version of the traditional pcap format. Tools such as Wireshark (and tshark) can process complete pcapng frames, while tcpdump and other libpcap based tools (currently including Kismet) can process the simpler version of pcapng. The pcap-ng format allows for multiple interfaces and linktypes to be stored in a single file. This format can be read and processed by [Wireshark and tshark](https://www.wireshark.org) but may not be compatible with all traditional libpcap-based tools. Typically, libpcap based tools can easily process a pcap-ng file with a *single source* but may have difficulty processing files with multiple sources. The pcap-ng file can be post-processed with `tshark` or `wireshark` to strip it to a single interface if necessary. ## All packets Kismet can provide a live stream, in pcap-ng format, of all packets *since the time of this request* seen by Kismet from all datasources. To access packets *previously seen* by Kismet, look at the [kismetdb endpoints](/docs/devel/webui_rest/kismetdb/). * URL \\ /pcap/all_packets.pcapng /datasource/pcap/all_sources.pcapng * Methods \\ `GET` * Results \\ A pcap-ng stream of packets which will stream indefinitely as packets are received. ## Packets by datasource The packet stream may be limited to packets captured by a single datasource, indicated by the datasource UUID. * URL \\ /datasource/pcap/by-uuid/*[UUID]*/*[UUID]*.pcapng * Methods \\ `GET` * URL parameters: | Key | Description | | --- | ----------- | | *[UUID]* | Datasource UUID | * Results \\ A pcap-ng stream of packets which will stream indefinitely as packets are received. ## Packets by device The packet stream may be limited to packets captured and associated with a specific device by Kismet, indicated by the Kismet device key. * URL \\ /devices/by-key/*[KEY]*/pcap/*[KEY]*.pcapng * Methods \\ `GET` * URL parameters: | Key | Description | | --- | ----------- | | *[KEY]* | Device key | * Results \\ A pcap-ng stream of packets which will stream indefinitely as packets are received. kismet-docs-master/devel/rest/071-packet_filter.md000066400000000000000000000253401372362651600223270ustar00rootroot00000000000000--- title: "Filters" permalink: /docs/devel/webui_rest/filters/ toc: true docgroup: "devel-rest" excerpt: "Dynamically control filtering options to include or exclude devices and packets; the filtering API is used by multiple components in Kismet to define filters." --- ## Packet filters Packet filtering is used by Kismet to limit the packets in some fashion; typically to restrict the packets being logged, returned in packet streams, and similar functions. The packet filtering system, like [device views](/docs/devel/webui_rest/device_views), functions as a common layer which is mapped by different components. ### Filter logic Kismet filters activate to *block* packets: A *positive* filter type *filters* or *excludes* the packet. When represented as boolean or integer values, a filter type of `true` or any non-zero value will *exclude* that match. Filter terms may match on packet attributes, dependent on the type of filter. Matches can operate as `filter` or `pass` to explicitly allow or block a match. Packets which do not match any filter terms are handled by the filter `default` behavior, which can be used to accept or reject all non-matching packets. The filter engine recognizes several terms when setting filtering: `true`, `reject`, `deny`, `filter`, and `block` are equivalent terms for telling the filter to exclude a match. `false`, `allow`, `pass`, and `accept` are equivalent terms for allowing a packet to pass a filter and be allowed. ## Common packet filter status * URL \\ /filters/packet/*[FILTERID]*/filter.json * Methods \\ `GET` `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Result \\ Dictionary of filter status, including description, default behavior, and type, optionally simplified. Additionally, the filter results may contain the filter terms, depending on the type of filter (for instance, `mac_addr` filters contain the mac address filtering tables). ## Common packet filter defaults The default method is applied to all packets which do not match any terms in the filter. * URL \\ /filters/packet/*[FILTERID]*/set_default.cmd * Methods \\ `POST` * URL parameters \\ | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | default | String value of the default behavior of the filter (`reject` or `allow` for instance) | * Result \\ `HTTP 200` on success \\ HTTP error on failure ## MAC address packet filter blocks MAC address filters use the type `mac_filter`, and filter (perhaps obviously) by MAC address. Address filters can be applied to: * *source* - Original source device. In Wi-Fi networks, equivalent to the source MAC; in other phy types, typically the originating device. * *destination* - Target device. In Wi-Fi networks, the destination MAC; in other phy types, if present, the equivalent destination address. * *network* - Associated network. In Wi-Fi, this is the BSSID. * *other* - Other address; in Wi-Fi this is the fourth MAC found in WDS; in other phy types it represents some form of alternate address. * *any* - Matching any of the address fields. Address filters are applied in the above order: `source`, `destination`, `network`, `other`, `any`, `default`. If an address is accepted by the `source` stage and would be rejected by the `destination` stage, the filter will *accept* the packet, as this is the first operation. ### Defining filters Filters can be added to any of the filter blocks; `source`, `destination`, `network`, `other`, or `any`. * URL \\ /filters/packet/*[FILTERID]*/*[PHYNAME]*/*[BLOCKNAME]*/set_filter.cmd * Methods \\ `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | | *[PHYNAME]* | Name of PHY to apply filters to. MAC address filters are PHY specific. | | *[BLOCKNAME]* | Name of filter block (source, destination, network, other, or any) | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | filter | Dictionary object where the MAC address is the key and a boolean filter term is the value. These filters will be added to the block identified by *[BLOCKNAME]*. A value of `true` indicates the matching MAC address *will be blocked*, while a value of `false` indicates the matching MAC address *will be passed*. [Masked MAC addresses](/docs/devel/webui_rest/keys_and_macs/) can be supplied for bulk matching. | * Result \\ `HTTP 200` on success \\ HTTP error on failure * Notes \\ Packets which do not match a filter term will be passed to the default behavior of the filter. Setting a filter to `false` does *not remove the match*. Use the *filter removal API* to remove matches. ### Removing filters Filters can be removed from any of the filter blocks; `source`, `destination`, `network`, `other`, or `any`. * URL \\ /filters/packet/[*FILTERID]*/*[PHYNAME]*/*[BLOCKNAME]*/remove_filter.cmd * Methods \\ `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | | *[PHYNAME]* | Name of PHY to apply filters to. MAC address filters are PHY specific. | | *[BLOCKNAME]* | Name of filter block (source, destination, network, other, or any) | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | addresses | Array of MAC addresses (or masked MAC addresses) to be removed from the target filter block identified by *[BLOCKNAME]*. | * Result \\ `HTTP 200` on success \\ HTTP error on failure ## Class filters Class-based filtering is used by Kismet to limit logging events, devices, or other non-packet options. The class filtering system, like [device views](/docs/devel/webui_rest/device_views), functions as a common layer which is mapped by different components. ### Filter logic Kismet filters activate to *block* matches: A *positive* filter type *filters* or *excludes* the match. When represented as boolean or integer values, a filter type of `true` or any non-zero value will *exclude* that match. Filter terms may match on many attributes, dependent on the type of filter. Matches can operate as `filter` or `pass` to explicitly allow or block a match. Objects which do not match any filter terms are handled by the filter `default` behavior, which can be used to accept or reject all non-matching objects. The filter engine recognizes several terms when setting filtering: `true`, `reject`, `deny`, `filter`, and `block` are equivalent terms for telling the filter to exclude a match. `false`, `allow`, `pass`, and `accept` are equivalent terms for allowing an object to pass a filter and be allowed. ## Common class filter status * URL \\ /filters/class/*[FILTERID]*/filter.json * Methods \\ `GET` `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Result \\ Dictionary of filter status, including description, default behavior, and type, optionally simplified. Additionally, the filter results may contain the filter terms, depending on the type of filter (for instance, `mac_addr` filters contain the mac address filtering tables). ## Common class filter defaults The default method is applied to all packets which do not match any terms in the filter. * URL \\ /filters/class/*[FILTERID]*/set_default.cmd * Methods \\ `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | default | String value of the default behavior of the filter (`reject` or `allow` for instance) | * Result \\ `HTTP 200` on success \\ HTTP error on failure ## MAC address class filter blocks MAC address filters use the type `mac_filter`, and filter (perhaps obviously) by MAC address. Address filters apply to a single record, depending on the use of the filter. ### Defining filters * URL \\ /classfilters/*[FILTERID]*/*[PHYNAME]*/set_filter.json * Methods \\ `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | | *[PHYNAME]* | Name of PHY to apply filters to. MAC address filters are PHY specific. | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | filter | Dictionary object where the MAC address is the key and a boolean filter term is the value. These filters will be added to the block identified by *[BLOCKNAME]*. A value of `true` indicates the matching MAC address *will be blocked*, while a value of `false` indicates the matching MAC address *will be passed*. [Masked MAC addresses](/docs/devel/webui_rest/keys_and_macs/) can be supplied for bulk matching. | * Result \\ `HTTP 200` on success \\ HTTP error on failure * Notes \\ Packets which do not match a filter term will be passed to the default behavior of the filter. Setting a filter to `false` does *not remove the match*. Use the *filter removal API* to remove matches. \\ Phy names which do not exist at the time of the filter being defined will be matched if a compatible phy type is registered in the future. ### Removing filters * URL \\ /classfilters/[*FILTERID]*/*[PHYNAME]*/remove_filter.json * Methods \\ `POST` * URL parameters | Key | Description | | ------ | ----------- | | *[FILTERID]* | Filter ID to modify | | *[PHYNAME]* | Name of PHY to apply filters to. MAC address filters are PHY specific. | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | addresses | Array of MAC addresses (or masked MAC addresses) to be removed from the target filter block identified by *[BLOCKNAME]*. | * Result \\ `HTTP 200` on success \\ HTTP error on failure kismet-docs-master/devel/rest/075-plugins.md000066400000000000000000000007451372362651600212020ustar00rootroot00000000000000--- title: "Plugins" permalink: /docs/devel/webui_rest/plugins/ toc: true docgroup: "devel-rest" excerpt: "Information about running Kismet plugins." --- Kismet plugins may be active C++ code (loaded as a plugin.so shared object file) or they may be web content only which is loaded into the UI without requiring additional back-end code. ## Plugin list * URL \\ /plugins/all_plugins.json * Methods \\ `GET` * Results \\ Returns array of activated plugins kismet-docs-master/devel/rest/080-streams.md000066400000000000000000000023451372362651600211710ustar00rootroot00000000000000--- title: "Streams" permalink: /docs/devel/webui_rest/streams/ toc: true docgroup: "devel-rest" excerpt: "Logging and long-running live exports of data are classified as streams and can be observed and manipulated via the stream API." --- A Kismet stream is linked to an export of data of prolonged length; for instance, packet capture logs to disk or streamed over the web API. Streams can be monitored and managed; a privileged user can close existing sterams. ## Streams list * URL \\ /streams/all_streams.json * Methods \\ `GET` * Result \\ Array of active streams ## Stream details * URL \\ /streams/by-id/*[STREAMID]*/stream_info.json * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[STREAMID]* | ID of stream to examine | * Results \\ Returns detailed stream information object ## Closing a stream Closing a stream cancels any data being transferred or stored. * URL \\ /streams/by-id/*[STREAMID]*/close_stream.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[STREAMID]* | ID of stream to close | * Results \\ `HTTP 200` on successful stream closure HTTP error on failure kismet-docs-master/devel/rest/085-logging.md000066400000000000000000000032421372362651600211430ustar00rootroot00000000000000--- title: "Logging" permalink: /docs/devel/webui_rest/logging/ toc: true docgroup: "devel-rest" excerpt: "View and control logging attributes live." --- Kismet uses a centralized logging architecture which manages enabling and tracking the status of logs. The logging system integrates with the [streaming sytem](/docs/devel/webui_rest/streams/) for long-running log files. ## Log drivers Log drivers handle a specific type of logfile. * URL \\ /logging/drivers.json * Methods \\ `GET` * Result \\ Array of supported log types ## Active logs Not all drivers are activated depending on the Kismet config optins. * URL \\ /logging/active.json * Methods \\ `GET` * Result \\ Array of activated logs. ## Enabling logs Logs can be enabled run-time. * URL \\ /logging/by-class/*[LOGCLASS]*/start.cmd * Methods \\ `GET` `POST` * URL parameters | Key | Description | | --- | ----------- | | *[LOGCLASS]* | Kismet log class to enable | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | title | Alternate log title, overriding the `kismet.conf` config for `log_title=` * Results \\ `HTTP 200` and log object for newly created log on success HTTP error on failure ## Stopping logs Logs can be stopped run-time. The log must be open and running to be stopped. * URL \\ /logging/by-uuid/*[LOGUUID]*/stop.cmd * Methods \\ `GET` * URL parameters | Key | Description | | --- | ----------- | | *[LOGUUID]* | Kismet log UUID to stop | * Results \\ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/086-poi.md000066400000000000000000000017011372362651600203030ustar00rootroot00000000000000--- title: "Points of interest" permalink: /docs/devel/webui_rest/poi/ toc: true docgroup: "devel-rest" excerpt: "Points-of-interest can be tagged live, allowing for integration of physical buttons or other scripts to make a kismetdb entry for future analysis." --- You can tag a time and location as a "point of interest" using the POI API. This API is only available when the `kismetdb` log is enabled. ## Create a POI A POI is entered in the `kismetdb` log file as a `snapshot` record of type `POI`. A POI will have the current GPS location and time, and an optional note. * URL \\ /poi/create_poi.cmd * Methods \\ `POST` * API added \\ `2019-03` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | note | Optional human-readable 'note' to be added to the POI log. | * Results \\ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/090-kismetdb.md000066400000000000000000000155361372362651600213240ustar00rootroot00000000000000--- title: "KismetDB logs" permalink: /docs/devel/webui_rest/kismetdb/ toc: true docgroup: "devel-rest" excerpt: "Kismet stores all of its information in the kismetdb log; by exposing interfaces to the kismetdb log via the REST api, it becomes possible to access not only the current data and live packet streams, but previously captured packets and events." --- If the Kismet Databaselog is enabled, Kismet will expose an API for extracting historic data. If the databaselog is not enabled, these APIs will not be available and will return an error. ## Packet filtering The `filter` options in are treated as logical `AND` statements: To match a packet, the packet must match *all* of the filter options passed in the command dictionary. In other words, a filter by time, datasource, and type, would *only* return packets within that time range, from that datasource, and of that type. Filter options should be sent as GET parameters URL-encoded, when using the GET REST endpoint, and in a command dictionary under the `filter` key when using the POST endpoint. ### Filter options 1. Time window Packets can be selected by a time window which may either be closed (both start and end times specified) or open (only start or end time specified). | Key | Type | Description | | --------------- | ------ | ------------------------------------------------------------ | | timestamp_start | double | Posix timestamp as double-precision value (seconds.microseconds) | | timestamp_end | double | Posix timestamp as double-precision value (seconds.microseconds) | 2. Datasource Packets may be limited to a single data source, specified by UUID | Key | Type | Description | | ---------- | --------- | --------------------------------- | | datasource | text UUID | UUID string of capture datasource | 3. Kismet device Packets may be limited to the specific Kismet device ID they belong to | Key | Type | Description | | --------- | ------- | ---------------- | | device_id | text ID | Kismet device ID | 4. Data type Limit matching to a specific data type / DLT (Data Link Type). This numeric DLT matches the libpcap link types and describes the physical frame type of the packet. | Key | Type | Description | | ---- | ------- | ----------- | | dlt | integer | PCAP DLT | 5. Frequency Match only packets on the given frequency, if frequency information is available from the data source. Data sources which cannot report frequency will report as `0`. | Key | Type | Description | | --------- | ------ | ---------------- | | frequency | double | Frequency in KHz | | frequency_min | double | Minimum frequency in KHz | | frequency_max | double | Maximum frequency in KHz | 7. Signal window Limit matching to a range of signal levels, which may be open (only min/max signal provided) or closed (min and max specified). Packets which have no signal data (such as packets captured by source types which do not support signal records) will have a reported signal of `0`. | Key | Type | Description | | ---------- | ---- | ----------------------- | | signal_min | int | Minimum signal (in dBm) | | signal_max | int | Maximum signsl (in dBm) | 8. Device addresses Limit matching by decoded device address, if available. Not all capture phys report device addresses as MAC addresses, however the majority do. | Key | Type | Description | | -------------- | -------- | ---------------------------------------------- | | address_source | text MAC | Source MAC address | | address_dest | text MAC | Destination MAC address | | address_trans | text MAC | Transmitter MAC address (such as the AP BSSID) | 9. Location window Limit matching by location. Location windows should always be bounded rectangles of minimum and maximum coordinates. Coordinates are in decimal floating-point format (LL.LLLLL) and will be converted to the normalized non-floating internal values automatically. | Key | Type | Description | | ---------------- | ------ | ------------------------ | | location_lat_min | double | Minimum corner latitude | | location_lon_min | double | Minimum corner longitude | | location_lat_max | double | Maximum corner latitude | | location_lon_max | double | Maximum corner longitude | 10. Packet size window Limit matching by packet size. Size windows can define minimum and maximum or only minimum or maximum ranges. | Key | Type | Description | | -------- | ---- | ----------------------------- | | size_min | int | Minimum packet size, in bytes | | size_max | int | Maximum packet size, in bytes | 11. Result limiting Limit total packets returned. | Key | Type | Description | | -------- | ---- | ----------------------------- | | limit | int | Maximum results to return | ## Fetching historic packets Packets can be fetched from the `kismetdb`, for all packets stored in the current session `kismetdb` log. * URL \\ /logging/kismetdb/pcap/*[TITLE]*.pcapng \\ /logging/kismetdb/pcap/*[TITLE]*.pcapng?option1=...&option2=... * API added \\ `2018-12` * Methods \\ `GET` `POST` * URL parameters | Key | Description | | --- | ----------- | | *[TITLE]* | File download title, does not impact pcap file generation. | Additionally, when using the `GET` URI, the [filter options](#filter-options) defined above are accepted as `HTTP GET` URL-encoded variables. * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | filter | A dictionary of the [filter options](#filter-options) defined above | * Result \\ `HTTP 500` error if the `kismet` log type is not enabled. \\ A pcapng stream will be generated of packets, if any, matching the filter options. This stream will be buffered at the rate that the client is able to download it, and the stream will be closed at the end of the query. * Notes \\ If the `kismet` log is not enabled, this endpoint will return an error. ## Dropping packets On very long-running Kismet processes, you may wish to purge old packets. These packets will be removed from the kismetdb log. * URL \\ /logging/kismetdb/pcap/drop.cmd * API added \\ `2018-12` * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | drop_before | A unix second timestamp value, packets older than `drop_before` will be deleted. | * Result \\ `HTTP 200` on success \\ HTTP error on failure kismet-docs-master/devel/rest/095-phydot11.md000066400000000000000000000107651372362651600211770ustar00rootroot00000000000000--- title: "Phy80211 Wi-Fi" permalink: /docs/devel/webui_rest/phy80211/ toc: true docgroup: "devel-rest" excerpt: "The 802.11 Wi-Fi subsystem defines a set of Wi-Fi specific APIs for accessing information about APs, related devices, and more." --- The 802.11 Wi-Fi phy defines extra endpoints for manipulating Wi-Fi devices seen by Kismet, and for extracting packets of special types. ## WPA Handshakes The WPA handshake is vital for extracting the WPA key of an encrypted WPA or WPA2 session. Kismet will retain the handshake packets from an access point, and can provide them as a PCAP file. * URL \\ /phy/phy80211/by-key/*[DEVICEKEY]*/*[DEVICEKEY]*-handshake.pcap * Methods \\ `GET` * GET parameters | Key | Description | | --- | ---------- | | *[DEVICEKEY]* | Kismet device key of target device | * Result \\ On success: PCAP file of WPA handshake packets associated with the device, as well as a beacon packet. On error: HTTP error ## WPA PMKID The WPA PMKID component of the handshake can be used to perform offline attacks against the WPA key using Aircrack or Hashcat. Kismet will retain a packet with the RSN PMKID value, and can provide it as a PCAP file. * URL \\ /phy/phy80211/by-key/*[DEVICEKEY]*/*[DEVICEKEY]*-pmkid.pcap * API added: \\ `2019-05` * Methods \\ `GET` * GET parameters | Key | Description | | *[DEVICEKY]* | Kismet device key of target device | * Result \\ On success: PCAP file of RSN PMKID packet, and a beacon packet. On error: HTTP error ## Wi-Fi per-device pcap stream Kismet can provide a streaming pcap-ng log of all packets, from all interfaces, associated with a given Wi-Fi BSSID. Packets are streamed _starting when this endpoint is opened_, for past packtes, use the [KismetDB log API](/docs/devel/webui_rest/kismetdb/). * URL \\ /phy/phy80211/by-bssid/*[BSSID]*/*[BSSID]*.pcapng * Methods \\ `GET` * URL parameters | Key | Description | | - | - | | *[BSSID]* | BSSID retrieve packets from | * Results \\ A pcap-ng stream of packets which will stream indefinitely as packets are received. * Notes \\ See the [packet capture API](/docs/devel/webui-rest/packet_capture/) for more information about pcap-ng streams ## Wi-Fi clients Kismet tracks client association with access points. This information is available as a list of the device keys in the access point device record, but it is also available through the clients API which will return the complete device record of the associated client. * URL \\ /phy/phy80211/clients-of/*[DEVICEKEY]*/clients.json * Methods \\ `GET` `POST` * URL parameters | Key | Description | | - | - | | *[DEVICEKEY]* | Device to fetch clients of. This should be an access point device; providing a non-access-point device will return an empty set. | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ An array of device records of associated clients. ## Access points only view The 802.11 subsystem uses [device views](/docs/devel/webui_rest/device_views/) to provide a list of Wi-Fi access points. * URL \\ /devices/views/phydot11_accesspoints/... /devices/views/phydot11_accesspoints/devices.json /devices/views/phydot11_accesspoints/last-time/*[TIMESTAMP]*/devices.json * Notes \\ See the [views api](/docs/devel/webui_rest/device_views/) for more information ## Wi-Fi related devices Kismet can provide a list of related devices. Devices are related in 802.11 when they appear to be on the same physical network, or make up multiple BSSIDs in a roaming SSID. This can be seen when multiple APs share the same SSID, common clients, and appear as clients of each other. * URL \\ /phy/phy80211/related-to/*[DEVICEKEY]*/devices.json * Methods \\ `GET` `POST` * API added \\ `2019-03` * URL parameters | Key | Description | | - | - | | *[DEVICEKEY]* | Device to fetch relationships for. This device should be an access point. Providing a non-access-point device will return an empty set. | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \\ An array of device records of related devices. kismet-docs-master/devel/rest/100-phydot11_fingerprint.md000066400000000000000000000106671372362651600235720ustar00rootroot00000000000000--- title: "Wi-Fi fingerprinting" permalink: /docs/devel/webui_rest/phy80211_fingerprints/ toc: true docgroup: "devel-rest" excerpt: "Live manipulation of the fingerprinting system, which will be used in the future for whitelisting, alerts, and complex Wi-Fi device tracking." --- The Kismet phy80211 fingerprinting system is used for device whitelisting, device modification alerts, and other device tracking. The fingerprint API can be found under multiple paths, but all will follow this API. (Documentation to be improved as final paths are chosen). __This api is currently incomplete__ and under development. ## Fingerprints * URL \\ .../fingerprints/all_fingerprints.json * Methods \\ `GET` * Results \\ Array of all defined fingerprints. ## Adding fingerprints New fingerprints can be defined run-time. * URL \\ .../fingerprints/new/insert.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | macaddr | MAC address of fingerprint device | | beacon_hash | (optional) Kismet xxhash32 hash for static beacon IE fields, as found in the `dot11.device/dot11.device.beacon_fingerprint` field | | probe_hash | (optional) Kismet xxhash32 hash for static probe IE fields, as found in the `dot11.device/dot11.device.probe_fingerprint` field | | response_hash | (optional) Kismet xxhash32 hash for static response IE fields, as found in the `dot11.device/dot11.device.response_fingerprint` field | * Results \\ `HTTP 200` on success HTTP error on failure ## Updating fingerprints Fingerprints may be modified at run-time. * URL \\ .../fingerprints/by-mac/*[MACADDRESS]*/update.cmd * Methods \\ `POST` * URL parameters | Key | Description | | -- | -- | | *[MACADDRESS]* | MAC address of device fingerprint to be updated | * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | beacon_hash | (optional) Kismet xxhash32 hash for static beacon IE fields, as found in the `dot11.device/dot11.device.beacon_fingerprint` field | | probe_hash | (optional) Kismet xxhash32 hash for static probe IE fields, as found in the `dot11.device/dot11.device.probe_fingerprint` field | | response_hash | (optional) Kismet xxhash32 hash for static response IE fields, as found in the `dot11.device/dot11.device.response_fingerprint` field | * Results \\ `HTTP 200` on success HTTP error on failure ## Removing fingerprints * URL \\ .../fingerprints/by-mac/*[MACADDRESS]*/delete.cmd * Methods \\ `POST` * URL parameters | Key | Description | | -- | -- | | *[MACADDRESS]* | MAC address of device fingerprint to be deleted | * POST parameters \\ None * Results \\ `HTTP 200` on success HTTP error on failure ## Bulk-create fingerprints Sometimes it may be necessary to creaate a large number of new fingerprints at once. This API facilitates doing that in a single query. __LOGIN REQUIRE__D * URL \\ .../fingerprints/bulk/insert.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fingerprints | Array of fingerprint dictionaries to be inserted | Each entry in the `fingerprints` array must include: | Key | Description | | --- | ----------- | | macaddr | MAC address of fingerprint device | | beacon_hash | (optional) Kismet xxhash32 hash for static beacon IE fields, as found in the `dot11.device/dot11.device.beacon_fingerprint` field | | probe_hash | (optional) Kismet xxhash32 hash for static probe IE fields, as found in the `dot11.device/dot11.device.probe_fingerprint` field | | response_hash | (optional) Kismet xxhash32 hash for static response IE fields, as found in the `dot11.device/dot11.device.response_fingerprint` field | * Results \\ `HTTP 200` on success HTTP error on failure ## Bulk-delete fingerprints Similarly, it may be necessary to remove many fingerprints at once. __LOGIN REQUIRE__D * URL \\ .../fingerprints/bulk/delete.cmd * Methods \\ `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fingerprints | Array of fingerprint MAC address IDs to be removed. | * Results \\ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/101-phydot11_ssidscan.md000066400000000000000000000041131372362651600230400ustar00rootroot00000000000000--- title: "Phy802.11 SSID Scan module" permalink: /docs/devel/webui_rest/phy80211_ssidscan/ toc: true docgroup: "devel-rest" excerpt: "Still under development, the ssidscan module will allow for targetting devices by SSID and automatically searching for behavior." --- ## SSIDScan status Current configuration and status of the ssidscan module, including the target SSIDs and assigned datasources. * API added \ `2019-04` * URL \ /phy/phy80211/ssidscan/status.json * Methods \ `POST` `GET` * POST parameters \ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results \ `HTTP 200` on success HTTP error on failure ## SSIDScan configuration Push new configuration options to the ssidscan module, overriding any configuration present. * API added \ `2019-04` * URL \ /phy/phy80211/ssidscan/config.cmd * Methods \ `POST` * POST parameters \ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | ssidscan_enabled | Optional, boolean, enable or disable the ssidscan module | | ignore_after_handshake | Optional, boolean, ignore a target device once a WPA handshake has been captured | | max_capture_seconds | Optional, unsigned integer, maximum seconds to capture before returning to hop | | min_scan_seconds | Optional, unsigned integer, minumum seconds to scan before entering capture mode | | restrict_log_filters | Optional, restrict the kismetdb log to log only devices and packets meeting ssidscan targets. This will set filters but not remove existing logs. | | locking_datasources | Optional, vector of UUID strings of datasources assigned to the 'locking' pool to capture target devices | | hopping_datasources | Optional, vector of UUID strings of datasources assigned to the 'hopping' pool to scan for target devices | * Results \ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/102-phydot11_scansource.md000066400000000000000000000067111372362651600234050ustar00rootroot00000000000000--- title: "Phy802.11 Scanning-mode Sources" permalink: /docs/devel/webui_rest/phy80211_scansource/ toc: true docgroup: "devel-rest" excerpt: "A simple API for non-packet-capture 802.11 devices to report scanning results to Kismet" --- ## Scanning mode Properly capturing packets in Wi-Fi requires monitor mode and either a local Wi-Fi device or a high bandwidth connection. Scanning mode allows devices without special drivers to report networks to Kismet, but with some severe limitations: * Clients will not be visible. * The scanning mode device may transmit probe requests while scanning. * Enhanced information from the beacon such as max speed, etc, will often not be available. * Actual packet data will not be available. Scanning mode is really only appropriate for specific configurations, such as: * Mobile devices like Android or IOS reporting scan results to a central Kismet server * Embedded devices such as the ESP8266 or ESP32 ## Scanning mode datasources Scanning mode datasources are created dynamically by Kismet when reports are submitted; there is no need to define a specific scanning mode datasource prior to sending a report. A scanning mode report must include: 1. A datasource UUID. This ID must be unique within Kismet, and consistent between all reports from this scanning source. Scanning software should cache this UUID for consistency. 2. A human-readable name. This will be assigned as the name of the datasource, and will be updated if it changes. Scanning software should cache this name for consistency. ## Cache/burst mode reporting Scanning mode assumes that the device doing scanning is not able to maintain a constant connection to the Kismet server. Reports can be cached and send in groups using the report endpoint; each report can contain a timestamp, GPS location, and signal information, and multiple reports over time can be sent for a single AP. ## Scanning mode report A scanning mode report consists of a [command dictionary](/docs/devel/webui_rest/commands/) holding an array of reports. Virtual datasources for each new report are automatically created. * API added \ `2020-06` * URL \ /phy/phy80211/scan/scan_report.cmd * Methods \ `POST` * POST parameters \ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | reports | Array containing multiple report objects | | source_name | A unique, consistent source name for the virtual datasource reporting this scan. | | source_uuid | A unique, consistent source UUID for the virtual datasource reporting this scan. | A report object should contain: | Key | Description | | --- | ----------- | | timestamp | (Optional) Unix timestamp at second precision. If no timestamp is provided, the time of this message is used. Due to general lack of precision of scanning mode, timestamp is second only. | | ssid | (Optional) SSID | | bssid | BSSID | | capabilities | (Optional) An Android or Wigle style string of encryption options, such as `[WPS]`, `[WPA-PSK-TKIP+CCMP]`, `[WEP]`, and so on. | | channel | (Optional) Quoted string channel, such as `"6"`, `"42HT40P"` | | freqkhz | (Optional) Frequency of AP, in KHz | | signal | Signal, in dBm | | lat | (Optional) GPS latitude | | lon | (Optional) GPS longitude | | alt | (Optional) GPS altitude | | speed | (Optional) GPS speed | * Results \ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/103-phydot11_ssidtracker.md000066400000000000000000000060211372362651600235510ustar00rootroot00000000000000--- title: "SSID views" permalink: /docs/devel/webui_rest/phy80211_ssid_tracker/ toc: true docgroup: "devel-rest" excerpt: "A dedicated SSID aggregator API" --- ## SSID tracker The SSID tracker is a phy80211 specific mechanism for mapping SSID broadcast, probe, and response. A unique identifier is generated from the SSID content, length, and encryption options. Each SSID is mapped to a list of device keys organized by probe, response, and advertisement. ### SSID-based summarization and display Mirroring the [base summarization & display endpoint](/docs/devel/webui_rest/devices/#old-summarization--display) API, the SSID summarization endpoint is the primary interface for clients to access the SSID list and for scripts to retrieve lists of SSIDs. The SSID summarization is best utilized when applying a view window via the `start` and `length` variables. * URL /phy/phy80211/ssids/views/ssids.json * API added `2020-04` * Methods `POST` * POST parameters A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------- | ----------------------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | | colmap | Optional, inserted by the Kismet Datatable UI for mapping column information for proper ordering and sorting. | | datatable | Optional, inserted by the Kismet Datatable UI to enable datatable mode which wraps the output in a container suitable for consumption by jquery-datatables. | Additionally, when in datatables mode, the following HTTP POST variables are used: | Key | Description | | --- | ---- | | start | Data view window start position | | length | Datatable window end | | draw | Datatable draw value | | search[value] | Search term, applied to all fields in the summary vector | | order\[0\]\[column\] | Display column number for sorting, indexed with colmap data | | order\[0\]\[dir\] | Sort order direction from jquery-datatables | * Results Summarized array of SSIDs ### SSID details Similar to the device details endpoint, a SSID details endpoint provides all the information about a tracked SSID entity. * URL /phy/phy80211/ssids/by-hash/*[HASH]*/ssid.json * API added `2020-08` * Methods `GET`, `POST` * URL parameters | Key | Description | | ------ | ---------------------------------------- | | *[HASH]* | Hash ID of the target SSID record | * POST parameters A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | ------- | ----------------------------------------------------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Results SSID record kismet-docs-master/devel/rest/105-phyuav.md000066400000000000000000000013411372362651600210200ustar00rootroot00000000000000--- title: "UAV / Drones" permalink: /docs/devel/webui_rest/phyuav/ toc: true docgroup: "devel-rest" excerpt: "Kismet can track additional information about UAV/Drone/Quadcopter devices based on manufacturer, SSID, and packet contents." --- The UAV/Drone phy defines extra endpoints for matching UAVs based on manufacturer and SSID. ## UAV manufacturers * URL \\ /phy/phyuav/manuf_matchers.json * Methods \\ `GET` `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Result \\ Array of manufacturer match records kismet-docs-master/devel/rest/110-phybluetooth_bluetoothscan.md000066400000000000000000000055731372362651600251730ustar00rootroot00000000000000--- title: "PhyBluetooth Scanning-mode Sources" permalink: /docs/devel/webui_rest/phybluetooth_scansource/ toc: true docgroup: "devel-rest" excerpt: "A simple API for non-packet-capture bluetooth scanning results" --- ## Scanning mode datasources Scanning mode datasources are created dynamically by Kismet when reports are submitted; there is no need to define a specific scanning mode datasource prior to sending a report. A scanning mode report must include: 1. A datasource UUID. This ID must be unique within Kismet, and consistent between all reports from this scanning source. Scanning software should cache this UUID for consistency. 2. A human-readable name. This will be assigned as the name of the datasource, and will be updated if it changes. Scanning software should cache this name for consistency. ## Cache/burst mode reporting Scanning mode assumes that the device doing scanning is not able to maintain a constant connection to the Kismet server. Reports can be cached and send in groups using the report endpoint; each report can contain a timestamp, GPS location, and signal information, and multiple reports over time can be sent for a single AP. ## Scanning mode report A scanning mode report consists of a [command dictionary](/docs/devel/webui_rest/commands/) holding an array of reports. Virtual datasources for each new report are automatically created. * API added \ `2020-07` * URL \ /phy/phybluetooth/scan/scan_report.cmd * Methods \ `POST` * POST parameters \ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | reports | Array containing multiple report objects | | source_name | A unique, consistent source name for the virtual datasource reporting this scan. | | source_uuid | A unique, consistent source UUID for the virtual datasource reporting this scan. | A report object should contain: | Key | Description | | --- | ----------- | | timestamp | (Optional) Unix timestamp at second precision. If no timestamp is provided, the time of this message is used. Due to general lack of precision of scanning mode, timestamp is second only. | | btaddr | Bluetooth MAC address | | name | (Optional) Advertised device name | | devicetype | (Optional) Device type, if known | | txpowerlevel | (Option) Device advertised powerlevel (Integer) | | pathloss | (Optional) Path loss (Integer) | | signal | (Optional) Signal, in dBm (Integer) | | scan_data | (Optional) Binary scan data, as hex string | | service_data | (Optional) Dictionary of service UUID to service scan data as hex strings | | lat | (Optional) GPS latitude (Float) | | lon | (Optional) GPS longitude (Float) | | alt | (Optional) GPS altitude (Float) | | speed | (Optional) GPS speed (Float) | * Results \ `HTTP 200` on success HTTP error on failure kismet-docs-master/devel/rest/_base.md000066400000000000000000000007561372362651600202630ustar00rootroot00000000000000--- title: "xyz" permalink: /docs/devel/webui_rest/xyz/ toc: true --- ## System status * URL \\ * Methods \\ `GET` `POST` * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | * Result \\ Dictionary of Kismet system-level status, including update, battery, memory, and thermal data, optionally simplified. kismet-docs-master/devel/rest/_links.md000066400000000000000000000006701372362651600204640ustar00rootroot00000000000000 * POST parameters \\ A [command dictionary](/docs/devel/webui_rest/commands/) containing: | Key | Description | | --- | ----------- | | fields | Optional, [field simplification](/docs/devel/webui_rest/commands/#field-specifications) | | regex | Optional, [regular expression filter](/docs/devel/webui_rest/commands/#regex-filters) | | timestamp | Optional, relative or absolute [timestamp](/docs/devel/webui_rest/commands/#timestamp) | kismet-docs-master/devel/tracked_component.md000066400000000000000000000440671372362651600217370ustar00rootroot00000000000000--- title: "Creating tracked components" permalink: /docs/devel/tracked_components/ toc: true docgroup: "devel-cpp" excerpt: "The tracked_component system is the Kismet internal architecture for introspectable and serializable data storage, and is used to define tracked structures like devices and protocol attributes." --- Kismet manages complex objects with arbitrary serialization and logging by implementing "tracked elements"; Tracked elements are introspectable in C++ and can be dynamically exported to other formats via the serialization API, such as JSON which is used heavily in the web interface. Tracked elements represent a compromise between the efficiency of native C++ types and the necessity of dynamic data handling and serialization. Unless you are writing a native C++ plugin, you do not need to worry about tracked elements at all; if you ARE, then there are some guidelines to follow. ## Anatomy of a `TrackerElement` Generally speaking a plugin should not define a new `TrackerElement` itself, it should implement a `tracked_component` (more on these in the next section); however they form the basic building blocks of both `tracked_component` and of the data held by custom components. All tracked elements are derived from `TrackerElement`; This super-class contains no actual data storage. Via subclassing and templates, `TrackerElement` implements basic scalar data types (non-POD basic data types such as `std::string`, `uuid`, `mac_addr` and similar), basic numeric types of the standard sizes (`uint8_t` through `uint64_t`, 4-byte `float` and 8-byte `double`), and various complex data types such as `vector` and `map`. `TrackerElement` subtypes are named accordingly, i.e.: * `TrackerElementString` * `TrackerElementUInt8` * `TrackerElementInt32` * `TrackerElementVector` * `TrackerElementDoubleMap` and can be found in `tracked_element.h`. ### Vectors and Maps `TrackerElement` represents complex data types in two main formats: 1. A `std::vector` or `std::map` of `TrackerElement` records. This allows constructing complex dictionary-like or list-like records of arbitrary fields, `tracked_component` complex records, MAC addresses, and so on. 2. Optimized `TrackedElementVectorDouble` and `TrackedElementDoubleMapDouble` which contain, respectively, raw `double` values and raw `double:double` key:value pairs. If your plugin stores purely numerical data, such as a vector of signal values, it is *significantly* more efficient to use the `TrackedElementVectorDouble` (or equivalent DoubleMapDouble) objects, and will consume less than half the RAM using a traditional `TrackerElementVector` would use. Each `TrackerElement` derivative also contains: 1. A `TrackerType::...` type which enforces type-safety on get/set operations 2. A `uint32_t` signature which is used to enforce type-safety on complex types 3. An optional local name Each derived type contains: 1. A get/set function for its type 2. Optional `coercive_set` functions which allow importing generic types (such as strings to UUID or mac_addr, and various precision numbers to numeric types) 3. A `clone_type` function which is responsible for returning a `std::unique_ptr` instance of a new object of this type, which is integral to the field creation and tracking system. 4. Optional additional support functions, such as standard STL iterator implementations for vector and map elements ## `TrackerElement` Lifecycle `TrackerElements` are nearly always stored and processed as C++11 `std::shared_ptr` smart-pointer managed objects. This allows usage counting and automatic deletion of a `TrackerElement`, which may be found hosted in many dynamic representations of data over its lifecycle. It is almost never necessary (or wise, or even possible) to create a naked `TrackedElement` or a naked `TrackedElement *` pointer. ## `tracker_component` A `tracker_component` is derived from a `TrackedElementMap`, which implements a dictionary of fields. Collections of data maintained and exposed by a plugin should be derived from the `tracker_component` class; Kismet uses this class to maintain all internal state about devices and other data, and a `tracker_component` can be directly inserted into an existing device record. The `tracker_component` also implements a collection of helper macros which will automatically define getter/setter functions, with optional casting, as well as support for dynamic field creation on first use. The `tracker_component` has all of the existing `TrackedElement` features, but also specifies two additional core functions: 1. `register_fields()` which is called during construction and is responsible for defining all the fields that this object needs (typically using the `register_field` function) 2. `reserve_fields(std::shared_ptr e)` which is called during construction and is responsible for allocating any *custom fields* which cannot, for some reason, be allocated automatically by the registration system. Typically the only actions which are needed here are re-typing complex fields during loading from stored data. ## Deriving from `tracker_component` Any data you wish to expose as an object must be derived from `tracker_component`. To do this, there are a number of functions you must implement. ### First, the Boilerplate: For our example, we want to mimic the behavior of the Kismet messagebus so that we can display messages on the web UI. We need to create a message record which has a timestamp, the message content, and a set of flags. ```C++ class WebTrackedMessage : public tracker_component { public: // tracker_component base constructor WebTrackedmessage() : tracker_component() { // We always have to call register and reserve register_fields(); reserve_fields(NULL); } // Constructor which takes the ID WebTrackedMessage(int in_id) : tracker_component(in_id) { // We always have to call register and reserve register_fields(); reserve_fields(NULL); } // The final default constructor, which takes both and ID and a pointer to // existing object data; this is used to craft a custom object from a base // which already contains these fields; this can happen when loading stored // data or deserializing IPC data WebTrackedMessage(int in_id, std::shared_ptr e) : tracker_component(in_id) { // Again the register and reserve, but this time we pass the // pre-existing element to the reserve_fields object register_fields(); reserve_fields(e); } // We need to provide a signature for this type, since all tracker_components // are TrackerType::TrackerMap at their base; typically this signature can be // a quick checksum of the type name. virtual uint32_t get_signature() const override { return Adler32Checksum("WebTrackedMessage"); } // Finally, we need to provide the clone type functions, which will // tell the field registration system how to create a field of our type // when loading data. These boilerplate implementations use the C++11 // decltype methods to automatically generate the proper type, but MUST // be included in every subclass! virtual std::unique_ptr clone_type() override { using this_t = std::remove_pointer::type; auto dup = std::unique_ptr(new this_t()); return std::move(dup); } virtual std::unique_ptr clone_type(int in_id) override { using this_t = std::remove_pointer::type; auto dup = std::unique_ptr(new this_t(in_id)); return std::move(dup); } // Finally, we need to provide a mechanism for cloning the type // of this custom object. When we add this object to the tracking // system which keeps track of named fields, this provides a // factory mechanism which builds a copy when requested. virtual shared_ptr clone_type() { return shared_ptr(new WebTrackedMessage(globalreg, get_id())); } } ``` This creates a tracked object, but there is nothing inside of it. To do that, we need to add some data fields. ### TrackerElement Fields For fields that are always present, we only need to track the field itself. Lets define some basic type fields; notice that we always define them as `std::shared_ptr`, and that we use the proper `TrackerElementXyz` sub-type for each. ```C++ protected: std::shared_ptr timestamp; std::shared_ptr message; std::shared_ptr flags; ``` ### Registering Fields To actually use the fields, they need to be initialized with a type and name. This is done in the `register_fields()` class method. ```C++ protected: virtual void register_fields() { // Call the parent register_fields() function, you MUST do this tracker_component::register_fields(); RegisterField("webmsg.message.timestamp", "message timestamp", ×tamp); RegisterField("webmsg.message.message", "message content", &message); RegisterField("webmsg.message.flags", "message flags", &flags); } ``` `RegisterField(...)` is part of the base tracker_component class, and handles the connection between a tracked data set and the tracking system which assigns fields. To register a field, you need: 1. A field name (which must be unique, you can ensure uniqueness by including your plugin type in the name; Kismet uses basic namespacing conventions to keep fields unique) 2. A human-readable description; this will be shown in the tracked_fields page and is helpful for future developers and consumers of your API 3. A *pointer* to the *shared pointer* where your field resides. This allows the field registration system to automatically create your fields and place them in your variables for you. `register_field` will return the internal id of the field which is created - most of the time this is not necessary, however when registering more complex objects or a dynamic object it may be necessary to save this ID. ### Accessing the Data: Proxy Functions Now that we have some data structures, we need to define how to access them. It's certainly possible to define your own get/set methods, but there are some macros to help you. The `__Proxy(...)` macro allows easy definition of a handful of methods in one line, at the expense of slightly obtuse syntax: `__Proxy(name, tracker type, input type, return type, variable)` This expands to define get and set functions (get_*name* and set_*name*) which accept *input type* variables and return *return type*, while automatically casting it to the type required by the TrackerElement, indicated by *tracker type*. What this really allows you to define in a single line cast-conversions between compatible types and define standard get/set mechanisms. For example, for a simple unsigned int element, `flags`, defined as `TrackerUInt32`, you might use: ```C++ public: __Proxy(flags, uint32_t, uint32_t, uint32_t, flags); ``` This would expand to define: ```C++ public: virtual uint32_t get_flags() const { return (uint32_t) GetTrackerValue(flags); } virtual void set_flags(uint32_t in) { flags->set((uint32_t) in); } ``` This looks fairly standard, but allows for more interesting behavior to be defined simply. For instance, we want to hold a standard unix timestamp (`time_t`) in the timestamp field, however there is no TrackerElement primitive for timestamps. However, if we do the following: ```C++ public: __Proxy(timestamp, uint64_t, time_t, time_t, timestamp); ``` Now we have a get and set pair of functions which accept `time_t` and transparently cast it to a `uint64_t` when saving or reading from the TrackerElement variable. The same trick can be used to make automatic get and set functions for any data type which can be cast directly to the internal tracked type. Additionally, individual get and set functions can be proxied via `__ProxyGet(...)` and `__ProxySet(...)` if you wish to only expose the get or set, or if you provide a custom get or set function which is more complex. Numerical values can also define `__ProxyIncDec(...)` or `__ProxyAddSub(...)` to generate increment/decrement (++ and --) and addition/subtraction functions automatically. Fields which represent a bitset can use `__ProxyBitset(...)` to define bitwise set and clear functions. There are some other tricks for accessing data which is represented by complex data types, we'll cover them later. ### Building from other Data Structures Often you will want to automatically populate a tracked component from an existing data structure. Due to how trackercomponents are generated, it is not possible to extend the constructors and import data that way, however creating a function for importing data is trivial, especially once the `__Proxy(...)` functions are defined. To continue our Messagebus example, let's define a method for adapting a message to our tracker_component: ```C++ public: void set_from_message(string in_msg, int in_flags) { // Since we used __Proxy to define get and set functions, we'll // call them instead of doing custom get/set and risking doing // it wrong. set_timestamp(globalreg->timestamp.tv_sec); set_message(in_msg); set_flags(in_flags); } ``` #### Accessing from outside the object It may be necessary to allow access from outside callers. This is only required for other code directly accessing your object; for exporting your data via the REST interface and other serialization methods, so long as your data is in `TrackerElement` objects it will be handled automatically. If you do need to provide access to your data objects, there are several methods you can utilize: ##### Method one: Provide functions which interface to the complex type In some instances you may wish to write methods which provide access to the complex type. For example, assuming that `SharedTrackerElement example_vec` is a TrackerVector, and you wish to add the record `e` to it, it may make sense to implement access thusly: ```C++ public: void example_vec_push_back(SharedTrackerElement e) { example_vec->push_back(e); } ``` Essentially the same is hiding the internal data structure via your object API: `add_foo(...)` may internally add to the vector, without ever explicitly exposing the actual data types. ##### Method two: Proxy the TrackedElement directly By directly returning a pointer to the TrackedElement you can allow consumers to wrap the complex data themselves. A proxy macro similar to the others is provided: ```C++ public: __ProxyTrackable(example_vec, TrackedElementVector, example_vec); ``` `__ProxyTrackable(...)` takes a name, and the type of shared pointer to return. This can be used to automatically cast custom data objects to the proper type on access, here, we use TrackedElement and don't change anything. Finally, it takes the variable. A caller could use this via: ```C++ ... TrackedElementVector ev(foo->get_example_vec); for (TrackedElementVector::iterator i = foo->begin; i != foo->end(); ++i) { ... } ... ``` ## Serialization Serialization is handled by the `tracker_component` and `TrackerElement` system automatically. Since the types of the fields are introspectable, serialization systems should be able to export nested data automatically. The only aspect of serialization that a custom `tracker_component` class needs to consider is what happens prior to serialization. This is handled by the `pre_serialize()` method, and is called by any serialization/export class. This method allows the class to do any updating, averaging, etc before its contents are delivered to a REST endpoing, XML serialization, or other export. For example, the RRD object uses this method to ensure that the data is synced to the current time: ```C++ public: virtual void pre_serialize() { // Always call the parent in case work needs to be done tracker_component::pre_serialize(); // Call an internal funtion for adding a sample; we add '0' to our // current sample and set the time, this fast-forwards the RRD to // 'now' and computes history for us in case we didn't see an update // in a long time add_sample(0, globalreg->timestamp.tv_sec); } ``` ### Using `tracker_component` objects elsewhere Sometimes you will want to use a `tracker_component` in a class that is not, itself, a component: creating data for serialization is a good example. `tracker_component` objects can be created and used as normal, with one important exception: The internal object management system expects them to be managed via `shared_ptr<>`. Failure to pass the proper owning shared_ptr record can result in memory being freed prematurely. One uncommon condition happens when implementing high-level global constructs which are, themselves, trackable elements: for example, the `system_monitor` class provides its data by directly serializing itself. This must be accounted for by creating a `create_xyz(...)` method and assigning the initial `shared_ptr<>` reference to a `GlobalRegistry` variable. A more common condition is when creating temporary records for exporting, for instance, a temporary list of devices. In these cases, the `shared_ptr<>` reference can be held by the calling function until the task is complete: ```C++ int foo::bar() { auto c = std::make_shared(some_component_id); // Do stuff, 'c' is automatically freed when all references expire. // This can include passing it to a serializer, embedding it in an object // via add_map or similar, etc. } ``` It is important to remember that due to the mechanics of `shared_ptr<>` that two shared pointers created referencing the same object *are not identical*. There must be *one, single, canonical shared_ptr which defines an object*, and all other references must be copied from that pointer. Attempting to cast an existing object to a `shared_ptr<>` or creating a `shared_ptr<>` from a `this` pointer will result in multiple usage counts to the same memory and premature freeing of the object. kismet-docs-master/devel/webui.jquery.kismet.devicedata.md000066400000000000000000000237551372362651600242550ustar00rootroot00000000000000--- title: "Extending the webui - device data" permalink: /docs/devel/webui_devicedata/ toc: true docgroup: "devel-web" excerpt: "The web UI has pluggable interfaces for extending the device details window." --- It's often desirable to display simple data in Kismet as a table. Kismet handles this in the web UI as a jquery plugin, `jquery.kismet.devicedata`. `devicedata` takes a JSON object and a set of options, which includes a set of flexible field definitions able to map simple data/title pairs as well as filtering, complex render functions, empty field substitutions, and nested groups. ## Applying `$.devicedata()` `devicedata` can be applied to any entity, but generally only makes sense to apply to a `div` or similar container. ```html
``` ## Devicedata options A `devicedata` instance takes a small number of options and an array of field defintions which perform the heavy lifting of the table display. ### id - string (optional) Sets the entity ID of the table created by `devicedata`. Defaults to 'kismetDeviceData'. ### fields - array Array of field definitions, discussed in the next section. ## Devicedata fields The field definitions are where the magic happens in the `devicedata` plugin. They function similarly to `DataTable` column definitions - a field definition can provide a simple title/content map, or can insert fully rendered graphics, other objects, etc. Many options can be passed as a string or as a function. Functions all take an options dictionary object, containing at least: * **key** - String key of current field * **data** - Complete data set assigned to this `devicedata` object * **value** - Resolved value for the current field * **basekey** - Optional string key of base object, used in iterative groups (more on these later) * **base** - Object of the sub-set of data for the current field, used it iterative groups. Additional fields may be present in the options object depending on the callback, and will be mentioned below. ### field A Kismet-style field spec. This allows for addressing nested and index data by chaining the fields, for example, `kismet.device.base.signal/kismet.common.signal.last_signal_dbm`. ### title - string Title text presented to the user in the header for the row ### empty - string | function(opts) (optional) Text to be substituted if the key is not available in the data set. ### filter - function (optional) A function, taking a opts argument and returning boolean, which determines if this entire display is rendered or skipped. Filter functions should return `true` to display the field and `false` to hide it. ```javascript { ... filter: function(opts) { if (data[something]) return true; return false; } } ``` ### filterOnEmpty - boolean (optional) Filter this field if it is undefined, or an empty string. This is identical to comparing the value in a filter function. ### filterOnZero - boolean (optional) Filter this field if it is undefined, or a zero number. This is identical to comparing the value in a filter function. ### render - string | function (optional) If the render option is a string, it is placed in the HTML of the `` container. If the render option is a function, it will called during creation of the table row, and the returned string is placed directly in the cell, prior to completion of the entire table. The render function is called before the DOM of the container is finalized. Render functions may return complex HTML. The render function is called with a standard options dictionary. For example, a row rendering the timestamp as a human-readable time: ```javascript { field: "kismet.device.base.first_time", title: "First Seen", render: function(options) { return new Date(options['value'] * 1000); } }, ``` ### draw - function(opts) (optional) Draw function called AFTER creation of the table. This function can be used to manipulate the contents of the row (or entire table) after it has been created and rendered. The draw callback is mostly used for graphs or other non-text content. Draw is called after the DOM is finalized so can manipulate the objects directly. Draw functions receive the normal options object, with an additional value: * **container** - object container for the `` cell for this field. For example, to insert a sparkline in a row you could combine the `draw` and `render` functions: ```javascript { field: "some.data.array", title: "Sparkline", render: 'Graph coming soon'; draw: function(opts) { opts['container'].sparkline({data: opts['value'];}); } } ``` A more complex example could create themed elements in the `draw` function and later utilize them in the `render` function: ```javascript { field: "some.data", title: "Dynamid draw", render: '
', draw: function(opts) { var mydiv = $('div.custom', opts['container']); mydiv.html('Added dynamically in draw'); } } ``` ### groupTitle string | function (optional) Indicates that this is a sub-group and provides a user-visible title for the group. Sub-groups are rendered as a nested table, and fields defining a subgroup act as a top-level options directive - that is, they may then contain their own `id` and `fields` options. The `id` option is applied to the nested table, and the `fields` are placed inside the nested instance. In simpler terms, subgroups create a new `devicedata` table, which can, in turn, contain more fields, subgroups, etc. The `groupTitle` option can be a fixed string, or a function taking an options set. For example, to define a location group: ```javascript { // Indicate that we're a subgroup, and give it the title 'Avg. Location' groupTitle: "Avg. Location", // The subgroup doesn't apply to a specific field, so we give it a junk value field: "group_avg_location", // Assign an ID to our subgroup id: "group_avg_location", // Subgroups can have filters, too, so we query the data and see if we have // a valid location. If not, this subgroup will be hidden entirely filter: function(opts) { return (kismet.ObjectByString(opts['data'], "kismet.device.base.location/kismet.common.location.avg_loc/kismet.common.location.valid") == 1); }, // Fields in subgroup fields: [ { field: "kismet.device.base.location/kismet.common.location.avg_loc/kismet.common.location.lat", title: "Latitude" }, { field: "kismet.device.base.location/kismet.common.location.avg_loc/kismet.common.location.lon", title: "Longitude" }, ], } ``` ### groupIterate - boolean (optional) Indicated that this field contains an iterative group. Iterative groups apply to data sets like arrays or dictionaries. The group is treated like a subgroup, and loops over each value in the array or dictionary. Iterative groups treat the `fields` option slightly differently: all options for fields are processed as normal, however the field definition should be the field name only - the complete, indexed field path will be prepended automatically. It is simpler to provide an example. Given the data: ```javascript var data = { 'somegroup': [ { 'field1': "one", 'field2': "two" }, { 'field1': "three", 'field2': "four" } ] }; ``` A *standard* field definition might be `somegroup/field1`. However, for an iterative group, you would want to use: ```javascript { // We're an iterative group groupIterate: true, // Provide the GROUP FIELD, ie the dictionary or array object field field: 'somegroup', // Now our fields are referenced within `somegroup` automatically for us fields: [ { field: 'field1', title: 'Field One' }, { field: 'field2', title: 'Field Two' } ] } ``` Additionally, field functions called as part of an iterative group are given an additional option in the callback options: * **index** - The index value used for this iteration. ### iterateTitle - string | function (optional) Provide a title for an iterative group. May be a fixed string, or a function taking the standard options group. Additionally, the options group will contain: * **index** - The index value used for this iteration. ### span - boolean (optional) Spans the `` table cell containing the output across both columns (eliminating the title). This allows for rows with custom graphs to center them above the following columns, and other custom behavior. A spanned column will not show any title. For example to simply show the value, centered in bold across the entire column: ```javascript { field: "some_placeholder", span: true, render: function(key, data, value) { return '' + value + ''; } } ``` ### sanitize - boolean (optional) By default, devicedata fields are run through a sanitization function to convert HTML characters. If you are *sure your data is safe* (for instance, it is locally generated HTML content), this can be overridden. ## Manipulating Devicedata Tables Most of the requirements for manipulating the content of a Devicedata table should be met by the internal functions for rendering, drawing, etc. However, if you need to modify or access data from outside the Devicedata object, the following elements are created: * **table**, `id` using the supplied `id` field, class `kismet_devicedata`. This table is created for every group of fields - a devicedata table. The parent table uses the master `id` option, and subgroup tables are each created using the `id` of the subgroup definition. * **tr**, `id` using a sanitized field reference prefixed with `tr_`. To meet the requirements of an ID, complex field references (nested field names, indexed fields, etc) are converted by replacing all special characters with `_`. A field reference such as `foo_bar_baz.sub_field` will form the table ID `tr_foo_bar_baz_sub_field`. kismet-docs-master/devel/webui.md000066400000000000000000000561421372362651600173500ustar00rootroot00000000000000--- title: "Extending the web ui" permalink: /docs/devel/webui_basics/ toc: true docgroup: "devel-web" excerpt: "The web UI can be extended via Javascript and the UI pluggable interface, allowing for alterations and entirely new web UI systems." --- Kismet self-serves its web UI via the built-in webserver. The web UI can interact with any exposed REST endpoint on the server. Kismet does not currently support (direct) execution of CGI-style code (PHP, etc), active server-side code should be implemented via a Kismet plugin providing a new endpoint. ## Web UI Plugins A Kismet plugin can add onto the web UI by defining additional files which are loaded during the startup process. Add-on files can provide new content for existing elements or define entirely new mechanisms. ## Making a Module Kismet JS modules should follow some simple conventions to enable proper loading: * **All functions should be in a custom namespace**. This prevents overlap between common names in plugins and simplifies loading. * **A `load_complete` variable must be provided**. Because of how asynchronous loading of javascript is handled, the only way to know that a module has fully loaded and executed any setup functions is to scan a variable in the namespace of the module. ### A Basic Module ```javascript // Module boilerplate. This will define a module kismet-plugin-foo-js which // will instantiate under the global object kismet_plugin_foo. ( typeof define === "function" ? function (m) { define("kismet-plugin-foo-js", m); } : typeof exports === "object" ? function (m) { module.exports = m(); } : function(m){ this.kismet_plugin_foo = m(); } )(function () { "use strict"; // All functions and variables accessible outside this module are defined // in exports var exports = {}; // The first thing we MUST do is define load_complete and set it to 0 exports.load_complete = 0; // Define a function in our module which simply logs "hello" to the console exports.test_func = function() { console.log("Hello!"); } // We can perform any other on-load type actions here // Finally, set load_complete to 1, we've done everything we need to do exports.load_complete = 1; // Return our exports object return exports; }); ``` ## Device List The device list is the central component of the UI, showing the found devices, allowing the user to select devices to inspect, etc. Custom columns can be added to the device list via `kismet_ui.AddDeviceColumn(...)`. ### Defining a Column Columns are directly linked to the [jQuery DataTables](https://datatables.net/) implementation and share many characteristics. A column consists of a string ID (a unique value used for identifying this column in preferences), and an options dictionary. Columns can be defined as basic mappings of the JSON data in the device summary, custom transforms of the data, or complete custom drawing routines. #### sTitle - string Display title of the column. Passed as sTitle directly to the DataTables column definition. #### field - string path and optional rename value To tell Kismet which fields to include in the summary, the path to the field must be provided. The path follows normal Kismet field naming - for example, to included a nested signal structure, the field definition could be `'kismet.device.base.signal/kismet.common.signal.last_signal_dbm'`. When requesting common fields that might have overlapping names (such as location and signal fields), or simply to make referencing the field easier, an alternate name can be provided by passing an array, for example: `['kismet.device.base.signal/kismet.common.signal.last_signal_dbm', 'base.signal']`. #### description - string Human-readable *short* description of the column, used for displaying the column information in the settings pane. #### drawfunc - function (optional) Optional function for performing custom drawing when the row is visible. The devicetable is optimized to only call draw functions when the row is visible, so you don't need to worry about performing unnecessary work. The `drawfunc` function takes three arguments: * `dyncolumn`, the current column definition, which allows access to the name, id, and other fields passed to the `kismet_ui.AddDeviceColumn(...)` call * `datatable`, an object instance of the device table as a `.DataTable()` object, allowing access to the over-all data table records * `row`, an object instance of `.DataTable().row()` for the row being drawn. This is already resolved to the actual row, eliminating the concern for sorting or visible position resolution. #### name - string (optional) Optional name of the column definition. This allows searching by the column name in render functions to determine the index. #### orderable - boolean (optional) Passed to DataTables as bSortable, allows disabling sorting by this column. Most useful on graphical columns which don't contain sortable data. #### renderfunc - function (optional) Optional function for rendering the field. This is called as the `render` option of a DataTable row and takes the standard DataTable arguments: `data, type, row, meta`. Render functions must return an element to be inserted into the cell and are called before the entire row is assembled. #### sanitize - boolean (optional) By default, all data is passed through a function which escapes HTML characters; if your data is *known to be safe* (such as locally-generated format data) and you want to insert HTML directly into the row, set sanitize to false. #### searchable - boolean (optional) Passed to DataTables as bSearchable, controls if the content of the column is searchable from the quick search field. #### selectabe - boolean (optional) Column is selectable by the user (default: true). The most common use for creating an unselectable column is to pair it with the 'visible' option to create an invisible, but searchable, column (or a column which provides data to another column). #### visible - boolean (optional) Passed to datatables as bVisible, allows creating a column which is by default invisible. To create a column which the user cannot enable, team with 'selectable'. ### Example Columns To define a simple example column, you can call `kismet_ui.AddDeviceColumn(...)` any time before setting `load_complete=1` in your JS module. A not-very-useful example would be to define 'column_foo_channel' which simply maps the `kismet.device.base.channel` record and calls it 'Channel'. ```javascript kismet_ui.AddDeviceColumn('column_foo_channel', { sTitle: 'Channel', field: 'kismet.device.base.channel' }); ``` A more interesting example is to use the `renderfunc` option to render a custom timestamp, which is how the base UI renders the `time_t` unix timestamp as human-readable text. Like the previous example, all this code is placed before the `load_complete=1` in the JS module. First, we define a function which handles the render callback. This matches the DataTable render function for a column, and takes the same options: the data for the cell, the type of query, the full data for the row, and the row/column index information. ```javascript exports.renderLastTime = function(data, type, row, meta) { // Take the data, make a date from it, and slice the string return (new Date(data * 1000).toString()).substring(4, 25); } ``` Now that we have the callback function, we define the column to map the data and the render callback inside our module: ```javascript kismet_ui.AddDeviceColumn('column_foo_time', { sTitle: 'Last Seen', field: 'kismet.device.base.last_time', renderfunc: function(data, type, row, meta) { return renderLastTime(data, type, row, meta); }, }); ``` Finally, we'll show an example of doing custom drawing in a column. Because the render function happens too early, the easiest way to accomplish custom elements drawn on a row is to combine a render function which inserts a placeholder, and a draw function which gets called when that row is visible. Let's use the packet graph / sparkline RRD as an example. First we put placeholder text into the cell because we defer rendering until later: ```javascript exports.renderPackets = function(data, type, row, meta) { return "Preparing graph"; } ``` Then during the draw function we use jQuery selectors and the DataTable API to find the column (by name) and offset to the proper cell in the table, then we wipe its content and replace it with the sparkline: ```javascript function renderPackets(dyncolumn, table, row) { // Find the column by name using the 'foo:name' selector. Get the index // of the column, which is the cell # in the row. var rid = table.column(dyncolumn.name + ':name').index(); // Define a match using the array selector in jQuery, we want the // column id'th element var match = "td:eq(" + rid + ")"; // Fetch the data from the DataTable row record var data = row.data(); // Do a bunch of RRD manipulation to fast-forward our graph since we only // get updates when the network changes so we have to manually move forwards // in time if the network is visible but idle. This is also where we // average out the number of points in the graph so we get nice thick // sparkline bars which look a lot better. // Finally, render the sparkline. We use the jquery match we defined // above to search in the nodes of the row and grab the TD we want. // Then we call the jquery sparkline plugin and render directly into that // row. $(match, row.node()).sparkline(simple_rrd, { type: "bar", barColor: '#000000', nullColor: '#000000', zeroColor: '#000000' }); }; ``` Finally, we add the column like we do anywhere else. We set the `name` parameter so we can find the column by name later instead of hardcoded index. We set the field to the packets RRD object which we need Kismet to send us. ```javascript kismet_ui.AddDeviceColumn('column_foo_packet_rrd', { sTitle: 'Packets', field: 'kismet.device.base.packets.rrd', name: 'packets_foo', renderfunc: function(data, type, row, meta) { return renderPackets(data, type, row, meta); }, drawfunc: function(data, type, row) { return drawPackets(data, type, row); } }); ``` ## Device Details A device details window can be created by calling the `kismet_ui.DeviceDetailWindow(key)` function. For instance, to show a device detail for a known device key, ```javascript foo.on('click', 'div', function() { kismet_ui.DeviceDetailWindow(somekey); }); ``` ## Custom Device Details Plugins can add panes to device details windows via the `kismet_ui.AddDeviceDetail` API: `kismet_ui.AddDeviceDetail(id, name, priority, options);` ### id - string An ID for referencing the device details panel ### name - string User-readable name used for the title of the details panel ### priority - integer Order preference for the device details. Smaller numbers have a higher priority. In general, plugins should use a neutral priority, such as 50. ### options - dictionary An options object, containing the following: #### filter - function(data) - optional A function, returning if this details panel should be displayed. It is passed the data record for the device. A simple filter mechanism might be to compare the phy type, for example: ```javascript filter: function(data) { return (data['kismet.device.base.phyname'] === 'IEEE802.11'); } ``` #### draw - function(data, target) A function, responsible for populating the content of the details panel. It is passed the data record for the active device, and the element created for the details panel. A draw function can use any mechanism for populating the details panel. To replicate the standard system for displaying details, the `jquery.kismet.devicedata` module can be used (and is documented at [DeviceData](webui.jquery.kismet.devicedata.html)) ## Sidebar Menu Kismet has a (now standard) sidebar menu which is activated with the 'hamburger menu' in the top left of the UI. This is generally a good place to put features which are not otherwise directly accessible from the UI (for instance, independent windows which are not linked to device details, etc). The sidebar menu is managed by the `kismet_ui_sidebar` module which is loaded automatically before any dynamic modules. Sidebar items are automatically styled and wrapped in a div element which supports hovering animation. New menu items are added via `kismet_ui_sidebar.AddSidebarItem(options)`. The `options` parameter is a dictionary object with the following values: ### id - string (required) This is the ID assigned to the `
` element created in the sidebar. ### listTitle - string (required) This is the title of the menu item. This can included embedded HTML, and for consistency, it is recommended that an icon is selected from the included font-awesome icon font. ### clickCallback - string (required) The function in which is called which this item is clicked. This function is responsible for launching whatever activity corresponds to the menu item. The menu will be closed automatically when the item is clicked. ### priority - integer (optional) Where in the list to insert the new item. Smaller numbers indicate higher priority. In general, plugins should use a neutral priority (0) but in some cases it makes logical sense to place an option higher or lower in the list. ### An example sidebar We will, again, use our example module, `kismet_plugin_foo`. Our sidebar option will open an extremely simple jsPanel HTML5 window. ```javascript // Module boilerplate and other functionality // Define a function to launch our exports.PluginWindowDemo = function() { var demopanel = $.jsPanel({ id: 'sidedemo', headerTitle: 'Demo sidebar', headerControls: { controls: 'closeonely' }, content: 'Hello from the sidebar!', }).resize({ width: $(window).width() / 2, height: $(window).height() / 2 }).reposition({ my: 'center-top', at: 'center-top', of: 'window', offsetY: 20 }); }; // Add us to the sidebar with no specific priority kismet_ui_sidebar.AddSidebarItem({ id: 'sidebar_demo', listTitle: ' Demo Item', clickCallback: function() { return PluginWindowDemo(); } }); ``` ## Preferences / Settings Kismet provides a common settings panel, which plugins are strongly encouraged to use. A plugin can register multiple categories of settings. ### Settings windows Settings windows are registered via `kismet_ui_settings.AddSettingsPane(options)`, where options is a dictionary containing: #### id - string (required) Set the ID of this setting panel so that it can be referenced directly #### listTitle - string (required) The title of the settings group in the settings list #### windowTitle - string (optional) The title appended to the settings window when this group is selected. If no windowTitle is provided, the listTitle is used to make the window title. #### create - function (required) The create function is passed the content of the settings panel, and is responsible for populating it and creating any input callbacks. The create function is also called when the user clicks the 'Reset settings' button. #### save - function (required) The save function is passed the content element of the settings panel, and is called when the user opts to save the settings. The function should use HTML5 local storage for any browser-local settings, and can use this callback as an opportunity to call the server with changes. #### priority - integer (optional) Where in the settings list to add this item. Smaller numbers are higher in the list. In general, plugins should use a neutral priority (0). ### Settings Panels Settings panels are a vertically-scrolling panel, and generally constructed using the jquery-ui toolkit. For visual consistency, plugin settings should also use the jquery-ui methods when creating input forms. Settings should only be saved when the user clicks the 'Save' button in the settings panel - the `save` callback is called in the settings object passed to `AddSettingsPanel`. Settings plugins are responsible for telling the settings system when values are modified - this allows the settings window to show the 'Save Settings' button and the window-closing assistant. ### Launching directly to settings A specific settings panel can be shown automatically by launching directly to that settings id when opening the settings panel: ```javascript kismet_ui_settings.ShowSettings('demo_settings_panel'); ``` ### Example Settings An example settings group in a plugin module might look like: ```javascript // Define a function for creating and populating our settings panel function CreateSettings(elem) { // Create the object tree elem.append( $('
', { id: 'form' }) .append( $('
', { id: 'set_radio', }) .append( $('') .html("Radio example") ) .append( $('', { type: 'radio', id: 'demo_r_one', name: 'radioexample', value: 'one' }) ) .append( $('