Similar in general to output modification modules, pre-processed tokens (or FTokens) change the contents of a particular field. The key difference however, is:

Normal output modification modules change the content at output-time.
FTokens change the actual data as it is being processed, before the modular objective matches are applied.

The distinction may not be easy to understand at first, but the differences can be significant.

If, for example, you wished to create an objective that did the following: "Display out-of-hours logins for any Windows users, who work on the second floor of the building", then you would find it difficult to create an appropriate objective in Snare, without resorting to FTokens.

By default, Snare will be able to help you with the out-of-hours part of the query - each and every event sent to the Snare Central will incorporate a date/time. However, Windows does not know where users are physically located within the building, so there is nothing in the event for Snare to use, to detect whether a user is on the first, second or any other floor of the building.

This is where FTokens come into play. In order to determine on which floor a particular user works you will need to utilise the user name to interrogate an external database (eg: a web-accessible personnel application).

The first step in the process is to create a normal Snare Token called, for example, USERFLOOR. The source field would be the appropriate Windows security log username field (USERNAME, in most cases, but possibly DESTUSER depending on the events that you are interrogating). The regular expression would be simple, and all-inclusive: "(.*)".

The next step is to create a file, with the same name as the Token you wish to use as an FToken, appended with ".php" - eg: USERFLOOR.php. The file can be stored in /data/SnareUI/Global/FTokens, if this FToken should apply to ANY field called 'USERFLOOR', regardless of the log data source - or, it can be stored in /data/SnareUI/Global/FTokens/DATASOURCENAME - where DATASOURCENAME is the name of the data source (eg: CISCORouterLog, WinSecurity, Tru64Audit)

Token dialog, after the USERFLOOR.php FToken has been added

This file will utilise a function called 'GetData' to attempt to retrieve the floor that the user is a member of. The GetData function will replace the username, with the floor/level number, BEFORE the modular objective match query runs.

As such, despite the fact that the USERFLOOR token is, initially, merely a copy of the USERNAME/DESTUSER field, you can actually treat it as though it includes the user's floor information when you are constructing your search criteria.

Here is an approximation of the USERFLOOR FToken, using an imaginary web server that supplies username to floor information.

<?php
class USERFLOOR
{
  var $Table;
  var $UserFloorData;

  function USERFLOOR($table)
  {
    $this->UserFloorData=array();
    $this->Table=$table;

    # Read in our username to floor correlation information.
    # Assume DumpFloorData returns username,floor number
    $FloorInformation=file("http://personnelserver.dni.gov/DumpFloorData");

    if(!$FloorInformation) { return; }

    foreach($FloorInformation as $data) {
      list($username,$floor)=explode(",",$data);
      $this->UserFloorData[strtoupper($username)]=$floor;
    }
  }

  function GetData($username)
  {
    $username=strtoupper($username);
    return($this->UserFloorData[$username]);
  }
}
?>

Using this information, we can now construct a query in our modular objective something along the following lines:

FTOKENs are not supported by the version 8+ optimised query engine as at version 8.1.

When the updated query engine detects the presence of an FTOKEN in a query, it will use a fallback mode to send the query to the the previous query engine.

As such, queries that use FTOKENs may be significantly slower than normal queries in v8.1+.

Browser not supported