Updating and Extending

Over time, we expect that the database schema will change. To make transitioning to a new schema easier, each object is defined with the expected database columns defined in a class variable named column_names. The bulk data field (which contains json or raw packet capture) is in a class variable named bulk_data_field. The valid_kwargs class variable is used in parsing keyword arguments for filtering in the SQL query. These items tie into functions that live in the Utility class, and are used for forming the SQL that’s used to query the Kismet DB.

This tool follows calendar versioning, and new versions support DB schemas as far back as v4.

As the database schema changes, the changes required to support a new version of the db will be required on a per-object basis. The following object attributes are used to contain version-specific schema information:

• field_defaults: This is used to force a default value for fields that are not found in older-than-current versions of the Kismet DB.
• converters_reference: This allows us to specify a converter so that if the data type changes between schema versions, we can force the older DB type to match the current DB version’s type.
• column_reference: This describes the expected columns for each supported version of the kismet DB

All objects representing tables inherit from the BaseInterface class:

class kismetdb.BaseInterface(file_location)

Initialize with a path to a valid Kismet log file.

Parameters:file_location (str) – Path to Kismet log file.

Attribute:

bulk_data_field (str): Field containing bulk data (typically stored

as a blob in the DB). This allows the get_meta() method to exclude information which may have a performance impact. This is especially true for the retrieval of packet captures.

column_reference (dict): Top-level keys in this dictionary are version

numbers, and are used to easily extend the schema for new versions. The column_names attribute is populated from this during instantiation.

column_names (list): Name of columns expected to be in this object’s

table by this abstraction. Used for validation against columns in DB on instanitation.

column_map (dict): The keys are column names, and the values are

special handlers which allow enhanced filtering in database queries.

table_name (str): Name of the table this abstraction represents. valid_kwargs (str): This is a dictionary where the key is the name

of a keyword argument and the value is a reference to the function which builds the SQL partial and replacement dictionary.

field_defaults (dict): Statically set these column defaults by DB

version.

converters_reference (dict): This provides a reference for converters

to use on data coming from the DB on a version by version basis.

full_query_column_names (list): Processed column names for full query

of kismet DB. Created on instantiation.

meta_query_column_names (list): Processed column names for meta query

of kismet DB. Created on instantiation.

super_columns (dict): Pseudo-columns and relative queries are defined

here using objects like ColumnConplexTimestamp.

get_all(**kwargs)

Get all objects represented by this class from Kismet DB.

Keyword arguments are described above, near the beginning of the class documentation.

Returns:List of each json object from all rows returned from query. Return type:list

get_meta(**kwargs)

Get metadata columns from DB, excluding bulk data columns.

Keyword arguments are described above, near the beginning of the class documentation.

Returns:List of each json object from all rows returned from query. Return type:list

yield_all(**kwargs)

Get all objects represented by this class from Kismet DB.

Yields one row at a time. Keyword arguments are described above, near the beginning of the class documentation.

Yields:dict – Dict representing one row from query.

yield_meta(**kwargs)

Yield metadata from DB, excluding bulk data columns.

Yields one row at a time. Keyword arguments are described above, near the beginning of the class documentation.

Returns:Dict representing one row from query. Return type:dict