Events

Common Event Structure

All Weaklayer events have at least four fields: type, time, sensor and group. The events will be in JSON form and look something like this.

{
  "type":   "Install",
  "time":   1594209078132495,
  "sensor": "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":  "68886d61-572b-41a5-8edd-93a564fb5ba3",
  ...
}

type is a string that tells us which kind of event this is.
time is a positive integer indicating the time that event occurred at in epoch microseconds.
sensor is a UUID string that uniquely identifies the Weaklayer Sensor that the event is about.
group is a UUID string that uniquely identifies the group that the Weaklayer Sensor installed into.

Weaklayer events will have additional fields depending on the type of event that it is.

A Weaklayer event can be uniquely identified by its sensor and time fields, but you may want to use the type field as well. We will see events reference other events using time values.

The time value is measured in microseconds but the Weaklayer Sensor (a browser extension) only has time resolution in milliseconds. Therefore time values generated by the sensor use random numbers for the microsecond digits. The gateway does have microsecond resolution.

Install Events

Install events are generated by the Weaklayer Gateway. An install event is produced when a sensor successfully installs into a group by providing a valid install key. Here is an example.

{
    "type":         "Install",
    "time":         1594209020167364,
    "sensor":       "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
    "group":        "68886d61-572b-41a5-8edd-93a564fb5ba3",
    "label":        "Mitch's Laptop",
    "isNewInstall": true,
    "userAgent":    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:82.0) Gecko/20100101 Firefox/82.0"
}

label is the value provided in the Sensor Configuration label field.
isNewInstall indicated if this is the first time that this sensor has performed an install event. Sensors will perform many install events over their lifetime to renew auth tokens.
userAgent is the value that the gateway receives in the User-Agent HTTP header.

Install events provide metadata about the sensor that installed. Then this metadata does not need to be duplicated in other events.

Window Events

Window events are sensor generated. They correspond to the creation of a new javascript execution environment in the browser. Here is an example.

{
  "type":                    "Window",
  "time":                    1594209078132495,
  "sensor":                  "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":                   "68886d61-572b-41a5-8edd-93a564fb5ba3",
  "isTopLevelWindow":        true,
  "topLevelWindowReference": 1601950136204842
}

isTopLevelWindow indicates whether or not the window that was created is the top level. For example, an iframe inside of a webpage would trigger a Window event with isTopLevelWindow set to false.
topLevelWindowReference provides the time value for the top-level window that this window belongs to. If isTopLevelWindow is true, then the topLevelWindowReference and time fields in this event will have the same value.

Top-level windows are triggered by things like opening new tabs or visiting a website on a different domain. Non top-level windows are triggered by frames embedded inside of other windows. Depending on the implementation of a website, a new window might be created when navigating between pages on the same site.

WindowLocation Events

Window location events correspond to a given window visiting a particular web location. It gives the URL of the location. Here is an example.

{
  "type":            "WindowLocation",
  "time":            1594209078152194,
  "sensor":          "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":           "68886d61-572b-41a5-8edd-93a564fb5ba3",
  "protocol":        "https",
  "hostname":        "www.youtube.com",
  "port":            8443,
  "path":            "/",
  "search":          "",
  "hash":            "",
  "windowReference": 1594209078132495
}

protocol is the protocol of the URL. hostname is the domain name or IP address of the URL. port is the port of the URL. This is an optional field. A missing port value means that the default port for the protocol was used (e.g. 443 for https).
path is the path segment of the URL.
search is the search segment of the URL.
hash is the hash segment of the URL.
windowReference is the time value from the Window event corresponding to the window that visited this URL.

The Location object is a good reference for these field values.

TextInput Events

Text input events correspond to text values being input into a web page. Here is an example.

{
  "type":                    "TextInput",
  "time":                    1601950623362548,
  "sensor":                  "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":                   "68886d61-572b-41a5-8edd-93a564fb5ba3",
  "inputType":               "password",
  "textHash":                "kR8mTB/hc85+gKnpGXG6UuRlPFCLyyLmEt30hKoNhqM=",
  "textLength":              17,
  "windowLocationReference": 1601950622368245
}

inputType indicates the type of text that was inputted. Often, this is the type of input form element that the text was entered into. In the example above, the text was input into a password element. There are also the unknown and composite input types. These are used when the sensor does not have enough info to identify the input type or if the event was generated by the sensor composing text from multiple user inputs (e.g. keystrokes).
textHash is a base64 encoded HMAC-SHA256 of the text that was input into the web page. Each sensor generates its own unique HMAC key. This provides a layer of security over sensitive text, but allows for hashes from the same sensor to be compared.
textLength is the length of the piece of text this event is concerned with.
windowLocationReference is the time value from the WindowLocation event corresponding to the URL that this text was inputted into. Note that this reference can be followed to find the Window event for the window the text was inputted into.

Text input events can not be generated for every piece of text that is input into a web page. There would be too many. For example, if someone was typing the password hunter2 into a web page, a text input event could be generated for each of h, hu, hun, hunt, hunte, hunter and hunter2. Therefore the sensor tries to only creates text input events for pieces of text it deems important. This means that it ideally would only generate an event for hunter2 out of the above text pieces.